Update Contributing Docs #1915
Update Contributing Docs #1915
Conversation
- Update docs with all new tox hotness - Test running docs build: - `sphinx-build -a -b html -W docs/ docs/_build/` Fixes #1907
CONTRIBUTING.md
Outdated
| If you make changes to docs, you can test they still build locally too. | ||
|
|
||
| ```console | ||
| $ pip install docs/requirements.txt |
There was a problem hiding this comment.
| $ pip install docs/requirements.txt | |
| $ pip install -r docs/requirements.txt |
(haven't tested)
CONTRIBUTING.md
Outdated
| @@ -52,7 +77,7 @@ your PR. You may need to change | |||
| configuration for it to pass. | |||
|
|
|||
| For more `black-primer` information visit the | |||
| [documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#black-primer). | |||
| [documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#). | |||
There was a problem hiding this comment.
| [documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#). | |
| [documentation](https://github.com/psf/black/blob/master/docs/black_primer.md). |
| $ black-primer [-k -w /tmp/black_test_repos] | ||
| ``` | ||
|
|
||
| ### Docs Testing | ||
|
|
||
| If you make changes to docs, you can test they still build locally too. |
There was a problem hiding this comment.
Technically this step is also needed when you make modifications to documentation files which are duplicated (for reasons I don't really know / understand). But it really doesn't matter if the duplicated content is up to date since they will updated before it get deploys on ReadTheDocs as a fresh build always starts, and IMO GitHub isn't the right place for documentation hosting. IIRC one of the reasons why we duplicate the docs is because it improves the GitHub documentation reading experience, but we have ReadTheDocs already, a platform designed for documentation. I honestly wish and might try to get these duplicated files and the regen step gone for good.
edit: this ended up being a lot more ranty than I expected (the words in bold are what matter), apologies for the wall of text!
There was a problem hiding this comment.
I +1 this cleanup. I think it's not worth having the duplicates too.
I'm just keeping my PRs to address/solve one main problem with each, as you noted.
sphinx-build -a -b html -W docs/ docs/_build/Fixes #1907