Post about new configuration file #59
Conversation
Yes! I'd also include many more examples. I think now you're just stating benefits, but you should be showing people the benefits. Having some code examples of the YAML file would be a big win, especially around the neater stuff it can do.
I don't think this is important. Too "in the weeds". |
|
I've added some examples, and mention the internship (not sure if I should add more details here?). Also, I've mentioned some new stuff that we are planning (actually not sure if redirects will make it readthedocs/readthedocs.org#4221). |
| but the main advantages of using a configuration file over the web interface are: | ||
|
|
||
| - Some settings are only available using a configuration file | ||
| - The settings are per version rather than per project. |
There was a problem hiding this comment.
Firstly, talking about the advantages of the config file is fantastic 💯!
However, I'd like to see some more details of some of these advantages. That could go lower down in the body or it could go right here. Some of them like "settings live in version control" are pretty straight forward, but settings being per version rather than per project requires a bit of explanation. For example, this would allow different versions of docs to be built with different versions of Python or different requirements.
Co-Authored-By: stsewd <[email protected]>
configuration-file-v2.rst
Outdated
|
|
||
| - Some settings are only available using a configuration file. | ||
|
|
||
| We are moving away from using the web interface. |
There was a problem hiding this comment.
Is this meant to be a list item?
There was a problem hiding this comment.
It was a nested list, but it doesn't render correctly :/
configuration-file-v2.rst
Outdated
|
|
||
| - The settings are per version rather than per project. | ||
|
|
||
| This would allow different versions of docs to be built with different versions of Python |
There was a problem hiding this comment.
It feels weird to break up the list items like this, not sure what is trying to be done with it.
configuration-file-v2.rst
Outdated
| What did we change in the new version? | ||
| ------------------------------------- | ||
|
|
||
| - All valid options from the web interface are available. |
There was a problem hiding this comment.
This should probably have some introduction that isn't in bullet form. Having an entire section that is just bullets feels overly brief.
configuration-file-v2.rst
Outdated
| ------------------- | ||
|
|
||
| - Pipfile support | ||
| - Show the current configuration used in each build. |
There was a problem hiding this comment.
Again, it would be good to give more context here. A list item doesn't explain anything to the user. Each of these list items should instead be paragraphs, explaining the goal, why it would be good, and perhaps linking to an issue about it.
configuration-file-v2.rst
Outdated
|
|
||
| - Pipfile support | ||
| - Show the current configuration used in each build. | ||
| - Redirects per version of your docs. |
There was a problem hiding this comment.
An example of how this might be expanded:
Historically we've only supported redirects at the Project level, because we didn't have version level configuration. With the addition of our YAML file, we can now support per version redirects. One use case for this is when you migrate to a new file structure in your upcoming release, but want all your old documentation links to continue working. The work around this issue is being tacked in issue #xxx.
|
I've expanded the post, I'm replacing the nested lists for paragraphs |
Co-Authored-By: stsewd <[email protected]>
Co-Authored-By: stsewd <[email protected]>
|
👍 💯 🎉 |
I wasn't sure what to include, hope this first draft makes sense, feel free to point me any problem with the language/grammar/typos, etc D:
Should I included more technical details? Like we moved this module from a separated repo, and we did a lot of changes in the rtd code?
Should I include that this project was part of my internship in rtd?