Comment 1 by jteh on 2013-05-30 23:56
The DesignOverview document is very high level and technical in nature. It isn't really ideal for a developer who just wants to write a simple app module or plugin. It's more aimed at people who want to write more advanced code or dive into NVDA internals. In contrast, the Developer Guide is targeted at getting new developers started. I guess we could consider merging this into a later section of the Developer Guide, though.

As for the sections of the User Guide that the Developer Guide refers to, including them in the same document would mean duplicating those sections of the User Guide. Duplication is evil. :) I'd like to link them, but the problem is that the Developer Guide isn't distributed with NVDA itself but can be built by people running from source, so it has no reliable way of linking to the User Guide.

Thoughts are welcome, but duplication isn't an option.

CC @josephsl (current maintainer of NVDA's Developer Guide) for his thoughts/inputs on this documentation related proposal.

Long-term, I've been thinking we should consider combining all of our development documentation (including code documentation) into one single resource using Sphinx. While this does mean there is more work in documenting the code and we can't simply auto-generate all of the code documentation as Epydoc does, it has the added advantage that we can intersperse the code reference with explanatory text. We can also better order and structure the code reference. For example, for some classes (e.g. TextInfo), we have documentation for people calling the class, but we also have documentation for people subclassing it to provide their own implementations that others would use. In a purely auto-generated reference (such as with Epydoc), these two types of information get mixed together, whereas clear separation would be a huge help for intelligibility.

All that said, what I'm proposing here is an absolutely massive undertaking and would involve completely rethinking the way we write docstrings, etc.

As part of #9840, I started looking into Sphinx, which has also been mentioned here.

In my sphinx branch I created a prototype:

1. Install sphinx using pip: pip3 install sphinx
2. In the mentioned branch, navigate to the devDocs directory
3. Execute make html
4. Consult the _build folder for the output.

Note that the doc string annotations are still epydoc style. This is also a reason for many warnings. However, I've been able to get rid of all tracebacks at source code parsing time.

The dev docs is now created using sphinx. Specifically for this issue, in the readme of the NVDA repository, there is now a chapter called "get support" which brings the most important documentation sources into one place, from which you can easily access almost everything about NVDA's development environment.

I am closing this issue for now.