Much cleanup for configuration docs #674
Merged
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
* Clean up a lot of copy.
* Reduce usage of internal Sphinx concepts like "toctree"
* Make language clearer
* Fix a few factual inaccuracies
* Remove noisey/placeholder/introduction to a paragraph sort of text,
this just distracts readers.
* Make `confval` domain role to allow for creation of config value field
lists that are linkable and can be referenced. Also include
type/default fields
* Reduce redundancy in heading
* Intersphinx to Sphinx docs
* Use new role to intersphinx to Sphinx confvals
* Add copy on using logo/etc. These are common questions for us for
those not familiar with Sphinx. Link to appropriate docs.
|
An example of the output:
|
Blendify
reviewed
Sep 27, 2018
|
|
||
| :type: string | ||
|
|
||
| Change the Google Analytics ID that is included on pages. |
There was a problem hiding this comment.
Maybe note that this is not actually used yet?
| :type: boolean | ||
| :default: ``False`` | ||
|
|
||
| Only display the logo image, do not display the project name at the top of |
There was a problem hiding this comment.
Note that the version number will still be displayed?
There was a problem hiding this comment.
Should we document it yet? I can comment it out for now if it's effectively a noop.
jessetan
reviewed
Oct 1, 2018
jessetan
reviewed
Oct 1, 2018
jessetan
reviewed
Oct 1, 2018
jessetan
reviewed
Oct 1, 2018
jessetan
reviewed
Oct 1, 2018
jessetan
reviewed
Oct 1, 2018
jessetan
requested changes
Oct 3, 2018
|
Thanks for the feedback, and sorry it took a while to return to this! I edited with all of the above feedback and fixed a couple more issues on intersphinx linking. |
Blendify
approved these changes
Jan 24, 2019
jessetan
reviewed
Jan 26, 2019
| It's important to note that if you don't follow the same styling for your rST headers across | ||
| your documents, the toctree will misbuild, and the resulting menu might not show the correct | ||
| depth when it renders. | ||
| Currently the left menu will build based upon any ``toctree`` directives defined |
There was a problem hiding this comment.
Suggested change
| Currently the left menu will build based upon any ``toctree`` directives defined | |
| Currently the left menu will build based upon any :rst:dir:`sphinx:toctree` directives defined |
jessetan
approved these changes
Jan 26, 2019
|
LGTM with 1 comment (above) |
ericholscher
approved these changes
Feb 12, 2019
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.
this just distracts readers.
confvaldomain role to allow for creation of config value fieldlists that are linkable and can be referenced. Also include
type/default fields
those not familiar with Sphinx. Link to appropriate docs.