Skip to content
  • Leonard de Ruijter's avatar
    Use sphinx to create NVDA developer documentation (PR #9968) · e1e4a551
    Leonard de Ruijter authored
    Fixes #9840
    
    Summary:
    
    When we switched to Python 3, we had to abandon Epydoc for developer documentation.
    From the alternatives, sphinx seemed to be the most useful to us:
    - It is the only supported api doc generator on Read the Docs
    - It is used by numerous other projects, including python, wxPython, pyserial and configobj
    - It is heavily extensible.
    - In the end, it might allow us to integrate the user docs in the build process, thereby adding the ability to abandon txt2tags. Even if we don't, sphinx has markdown support with a simple extension.
    
    Implementation:
    
    Reimplements the functionality of `scons devDocs`, they are now build using sphinx.
    Move `devDocs` build script from `sconstruct` to the devDocs folder
    
    
    Issues:
    - The layout of the dev docs is likely to be broken, as we are still using epidoc style doc strings that have to be converted to the Python (restructured text) style doc strings
    - Read the Docs builds docs on Linux. If we want to support this, it will require some source code changes. We can work around a lot of cases using mock imports. We may be able to build the docs ourselves on CI and push them afterwards. 
    - No built in support for type hints, though there is an extension for that.
    
    Incompatible doc string syntax:
    Currently, we use epytext/epydoc style annotations for our doc strings. such as:
    	@param test: a parameter
    	@type test: int
    Sphinx uses directives like `:param` and `:type`. It also allows nesting them, e.g. `:param test int: a parameter`
    Another important prerequisite is that sphinx doc strings require an empty line between the doc string body and the parameter info.
    
    	"""This is a doc string.
    	:param test: this fails and isn't parsed correctly (i.e. printer literally)
    
    	:param test: this succeeds and is marked up correctly.
    	"""
    
    sphinx-epytext has been considered but that doesn't handle the empty line case.
    e1e4a551
This project manages its dependencies using pip. Learn more