Documentation changes (and small test fix) #151
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
While working on "overhauling" (re-organizing) the documentation, I've noticed a lot of repeated & out-dated informatuion. This will be fixed in several commits. This commit will: - Add a TOC & remove info better placed elsewhere from `~/README.md` - Fix some typos in README - Standardize apple OS as MacOS, not Mac OS(X) - Shorten the root readme to only contain info necessary for a quick start - Apply conststent .md formatting
Apply consistent markdown formatting (1 blank line, sequential header levels, etc.) and fix small typos. Also change iOS in bug_report to MacOS/Linux, since nobody will be running Aether on iOS
`doc/`'s markdown files were not organized, and had a lot of repeated information.
This commit (along with #42c8b97 and #38de72) should help address that.
There are still a number of gaps in doc coverage & some repeated information, but it should be easier to find specific information now.
Features:
- table of contents at ~/README.md and ~/doc/README.md
- I put this into a tree that made sense to me, open to suggestions on how to re-organize. Thinking about breaking off parts of doc/usage/ to doc/internals, but it's not done yet.
- Folders are Design (unchanged), Installing (package manager, cmake args, etc), and Usage (how to run, debug, and ensembles/indices).
- Add note that the "real documentation" is in the works... see github.com/AetherModel/AetherDevelopment
- I didn't want to touch this, but can migrate these README's there if it would be helpful.
- Add consistent markdown formatting. Did not change *too* much of the existing content. But re-organized it and fixed typos/style where necessary.
Spent a while debating whether to make this a GitHub Pages or add in to the RTD. Decided this would be easiest since it can be quickly adapted to either... But it's much less elegant that either would be. Navigation is particularly difficult, but I would imagine that people will start in the ~/README.md and then get linked to a specific page, then go back. Or will be hunting for a specific doc page which should be easier to find.
If it's not easier, I can re-organize or add more navigation options. I was afraid of deleting too much of the read-the-docs (since a lot of info there seems irrelevant), so didn't do anything there. But I can.
Note the code-of-conduct is still showing "problems" in a markdown linter, but I do not see it necessary to fix those. All other markdown files (outside of ~/.github/) show no errors.
Moving the files grid.md, ensembles.md, indices.md to new folder `docs/internal`. Should organize things a little better, but the folder name might need to be changed. ALSO: - Update the README's with the updated TOC's. - Consistent Markdown syntax: - consistent use of dashes/equals & hashtags for header level - no double empty lines - headings in descending-by-one order - denote links with <>'s - Add a language to each fenced (three backticks) code blocks
This commit adds ionGrid to the default aether.json file (in share/run/aether.json). The ionGrid specs set here hold no importance, but these three values need to be set to enable the tests to pass. Ideally, this is moved from the settings file to a function which reads the inputs (and either sets the default values or catches the error), but for now this works.
Drafted first in python. This code makes plots & is adjustable. I commented everything so it's hopefully understandable... Reach out with questions. Similar to SAMI2/3 grid. It's B_par & B_perp aligned, made in dipole (p,q) coords, and specified w/ (nf, nz). Code hands back (r,lat) though, not (q,p) or anything like that... Code needs to be able to be modified for tilted, offset dipole so I left all the for-loops and didn't spend any time optimizing.
…lizing mag grid Paper on this from 2006: <https://arxiv.org/pdf/physics/0606044>
…lizing mag grid Paper on this from 2006: <https://arxiv.org/pdf/physics/0606044>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Addresses:
In conversations with @aaronjridley, we decided a good use of time would be to lay out the
.mdfiles a little better. This has been done and is described along with each commit.In essence, the collection of markdown files at the root of the repository and within doc/ were repetitive and poorly referenced. I have rearranged a lot of the content (taking care to not remove anything), and added a table-of-contents and file tree (to show which files are available) where it made sense to.
Additionally, this PR changes a lot of the markdown formatting be consistent across all files. This includes headers in descending order, no double-blank lines, consistent use of dashes/equals or hashtags for headers within the same file, etc. Some typos fixed as well. No breaking changes, no fundamental changes to the content. Just a little cleaner to read, edit, and browse.
All files pass markdown linting, except the PR template... .github/bug_report.md was edited to change the example OS from iOS to MacOS/Linux. PR template untouched for the sake of consistency.
The final commit in this PR (5c984fe), however, does alter the default
aether.jsonfile in order to enable the tests to run successfully. I changed this file to include specifications for theionGrid. These changes do not need to be accepted, and the commit can be removed from the PR if a fix to the problem is in the works already.Type of change
Please delete options that are not relevant.
How Has This Been Tested?
Docs' formatting enforced with markdownlint within its VSCode extension.
Default
aether.jsontested by running Aether locally and also by watching the automated test run.Test configuration
Checklist:
develop(notmaster) branchCHANGELOG.md, summarizing the changes