Sphinx: remove 2.2.2 restriction and update readme regarding building source code docs locally #11973
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
NVDA docs can be built using more recent Sphinx releases such as 3.4.1. Therefore remove checking for Sphinx 2.2.2 in dev docs requirements.
…atement. Replace Epydoc with Sphinx. As a result, remove the Python 3 source dev docs limitation statement, as Sphinx will now build NVDA dev docs.
lukaszgo1
reviewed
Dec 27, 2020
| @@ -122,6 +121,7 @@ Although this [must be run manually](#linting-your-changes), developers may wish | |||
|
|
|||
| The following dependencies aren't needed by most people, and are not included in Git submodules: | |||
|
|
|||
| * To generate developer documentation: [Sphinx](http://sphinx-doc.org/), version 3.4.1 | |||
There was a problem hiding this comment.
This is inconsistent with the requirements file. I can imagine that someone reports an issue stating that readme asks to install specific version of Sphinx whereas requirements file installs whatever is the latest version at the time of installation. It'd be great to either remove specific version number from the readme, or enforce version 3.4.1 in the requirements file. I personally prefer the latter as we cannot guarantee that dev docs would always be buildable with the most recent version of Sphinx.
|
Hi, although not ideal, specifying a specific release can clarify things for now. Thanks for pointing this out.
|
Comment from Lukasz Golonka: specify Sphinx==3.4.1 to align with readme.
michaelDCurran
approved these changes
Jan 11, 2021
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.
Hi,
Possible oversight when Sphinx was introduced:
Link to issue number:
None
Summary of the issue:
When Sphinx was introduced, readme wasn't updated to point out that source code documentation can be built in Python 3 version of NVDA. Also, used this opportunity to remove Sphinx version restriction (latest release is 3.4.1, which succeeds in building source code docs).
Description of how this pull request fixes the issue:
Updates:
Sphinx requirement: remove version restriction.
Testing performed:
Built NVDA dev docs with Sphinx 2.2.2 and 3.4.1 with both succeeding.
Known issues with pull request:
None
Change log entry:
None
Thanks.