Repository: nvaccess/nvda

Issue:
Python 3: Restore developer documentation
Having the ability to run scons on Python 3 made us demolish the ability to create Python source code developer documentation temporarily. This is because epydoc isn't supported on Python 3.


Discussion:
I've looked into using Sphinx. Some things I found:

* Python, wxPython, PySerial and ConfigObj also use Sphinx
* It is an advised tool by readthedocs
* Installing it from pip requires some additional dependencies. It couldn't be expected from us that we bundle these all in git submodules. We could consider an additional binary repository, tough. I think this is preferred when we decide to use sphinx for more than just the developer documentation.
* It uses RestructuredText as the main code style. It has support for markdown, though only using an extra package. RestructuredText has other benefits over markdown, such as keywords and tables in the default spec.
* It supports type hints with an additional extension
* There is extensive documentation, many products use it.
* For our developer guide, it would be possible to link from the dev guide to module/class/function documentation.

In the current situation, we're using epytext/epydoc style doc strings. These are not compatible with sphinx by default. There is an additional [module](https://pypi.org/project/sphinx-epytext/) for this, which I haven't yet tested. I'm not convinced that this is the right direction though. May be we should convert everything to rst/sphinx native style. This shouldn't be very difficult. See [this article about a possible migration strategy](https://www.tomaz.me/2013/09/28/migrating-from-epydoc-to-sphinx-style-docstrings-using-sed-and-some-command-line-fu.html). There's also the [Pyment](https://github.com/dadadel/pyment) which I've tested quickly, but that tool doesn't replace the `L{link}` style markup from epydoc and tends to replace tabs with spaces.

Resolving patch:
diff --git a/devDocs/conf.py b/devDocs/conf.py
new file mode 100644
--- /dev/null
+++ b/devDocs/conf.py
@@ -0,0 +1,105 @@
+# A part of NonVisual Desktop Access (NVDA)
+# Copyright (C) 2019 NV Access Limited, Leonard de Ruijter
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.
+
+# Configuration file for the Sphinx documentation builder.
+
+# -- Path setup --------------------------------------------------------------
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../source'))
+import sourceEnv  # noqa: F401, E402
+
+# Initialize languageHandler so that sphinx is able to deal with translatable strings.
+import languageHandler  # noqa: E402
+languageHandler.setLanguage("en")
+
+# Initialize globalvars.appArgs to something sensible.
+import globalVars  # noqa: E402
+
+
+class AppArgs:
+	# Set an empty comnfig path
+	# This is never used as we don't initialize config, but some modules expect this to be set.
+	configPath = ""
+	secure = False
+	disableAddons = True
+	launcher = False
+
+
+globalVars.appArgs = AppArgs()
+
+# Import NVDA's versionInfo module.
+import versionInfo  # noqa: E402
+# Set a suitable updateVersionType for the updateCheck module to be imported
+versionInfo.updateVersionType = "stable"
+
+# -- Project information -----------------------------------------------------
+
+project = versionInfo.name
+copyright = versionInfo.copyright
+author = versionInfo.publisher
+
+# The major project version
+version = versionInfo.formatVersionForGUI(
+	versionInfo.version_year,
+	versionInfo.version_major,
+	versionInfo.version_minor
+)
+
+# The full version, including alpha/beta/rc tags
+release = versionInfo.version
+
+# -- General configuration ---------------------------------------------------
+
+default_role = 'py:obj'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+	'sphinx.ext.autodoc',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+	"_build"
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.
+
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Extension configuration -------------------------------------------------
+
+# sphinx.ext.autodoc configuration
+
+# Both the class’ and the __init__ method’s docstring are concatenated and inserted.
+autoclass_content = "both"
+autodoc_member_order = 'bysource'
+autodoc_mock_imports = [
+	"louis",  # Not our project
+]
+
+# Perform some manual mocking of specific objects.
+# autodoc can only mock modules, not objects.
+from sphinx.ext.autodoc.mock import _make_subclass  # noqa: E402
+
+import config  # noqa: E402
+# Mock an instance of the configuration manager.
+config.conf = _make_subclass("conf", "config")()


Test patch:
diff --git a/tests/lint/lintInstall/.gitignore b/tests/lint/lintInstall/.gitignore
--- a/tests/lint/lintInstall/.gitignore
+++ b/tests/lint/lintInstall/.gitignore
@@ -1 +1 @@
-_executed_requirements.txt
\ No newline at end of file
+_executed_requirements.txt