Skip to content

Sphinx: remove 2.2.2 restriction and update readme regarding building source code docs locally #11973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michaelDCurran merged 5 commits into from
Jan 11, 2021
Merged

Sphinx: remove 2.2.2 restriction and update readme regarding building source code docs locally #11973

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
84d6965
Sphinx: remove version requirement (2.2.2).
josephsl Dec 25, 2020
9ffbc13
Readme: replace Epydoc with Sphinx, and remove dev docs limitation st…
josephsl Dec 25, 2020
4374e11
Readme: document how to build source code docs with 'scons devDocs'.
josephsl Dec 25, 2020
818b371
Readme: output/DevDocs -> output/NVDA for source code documentation.
josephsl Dec 26, 2020
ca5701b
Dev docs/Sphinx: specify Sphinx 3.4.1 (December 2020 release).
josephsl Dec 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion devDocs/devDocsInstall/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
sphinx==2.2.2
sphinx==3.4.1
sphinx_rtd_theme
11 changes: 9 additions & 2 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,6 @@ Additionally, the following build time dependencies are included in Git submodul
* [Nulsoft Install System](https://nsis.sourceforge.io/Main_Page/), version 2.51
* [NSIS UAC plug-in](https://nsis.sourceforge.io/UAC_plug-in), version 0.2.4, ansi
* xgettext and msgfmt from [GNU gettext](https://sourceforge.net/projects/cppcms/files/boost_locale/gettext_for_windows/)
* [epydoc](http://epydoc.sourceforge.net/), version 3.0.1 with patch for bug #303
* [Boost Optional (stand-alone header)](https://github.com/akrzemi1/Optional), from commit [3922965](https://github.com/akrzemi1/Optional/commit/3922965396fc455c6b1770374b9b4111799588a9)

### Other Dependencies
Expand All @@ -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

@lukaszgo1 lukaszgo1 Dec 27, 2020 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

* To generate developer documentation for nvdaHelper: [Doxygen Windows installer](http://www.doxygen.nl/download.html), version 1.8.15:
* When you are using Visual Studio Code as your integrated development environment of preference, you can make use of our [prepopulated workspace configuration](https://github.com/nvaccess/vscode-nvda/) for [Visual Studio Code](https://code.visualstudio.com/).
While this VSCode project is not included as a submodule in the NVDA repository, you can easily check out the workspace configuration in your repository by executing the following from the root of the repository.
Expand Down Expand Up @@ -216,7 +216,14 @@ scons developerGuide
```

The developer guide will be placed in the `devDocs` folder in the output directory.
Note that the Python 3 sources of NVDA currently do not support building NVDA developer documentation using the `scons devDocs` command.

To generate the HTML-based source code documentation, type:

```
scons devDocs
```

The documentation will be placed in the `NVDA` folder in the output directory.

To generate developer documentation for nvdaHelper (not included in the devDocs target):

Expand Down