Merge pull request #252 from mfesiem/master

Add documentation with Sphinx and publish it to Read The Docs.

Author: adiroiban

.gitignore

@@ -10,3 +10,4 @@ _trial_temp/
 apidocs/
 *.egg-info
 .eggs
+docs/source/help.txt

CONTRIBUTING.rst

@@ -0,0 +1,24 @@
+
+What can you do
+---------------
+
+If you like the project and think you could help with making it better, there are many ways you can do it:
+
+- Create a new issue for new feature proposal or a bug
+- Triage old issues that needs a refresh
+- Implement existing issues (there are quite some of them, choose whatever you like)
+- Help with improving the documentation (We still have work to do!)
+- Spread a word about the project to your colleagues, friends, blogs or any other channels
+- Any other things you could imagine
+
+Any contribution would be of great help and I will highly appreciate it! If you have any questions, please create a new issue. 
+
+.. Releasing a new package
+   -----------------------
+
+    Releasing a new version is done via GitHub Actions.
+    First commit the version update to master and wait for tests to pass.
+    Create a tag on local branch and then push it::
+
+        git tag 1.2.3
+        git push --tags

README.rst

@@ -1,125 +1,80 @@
 pydoctor
-========
+--------
 
 .. image:: https://travis-ci.org/twisted/pydoctor.svg?branch=tox-travis-2
   :target: https://travis-ci.org/twisted/pydoctor
 
 .. image:: https://codecov.io/gh/twisted/pydoctor/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/twisted/pydoctor
 
+.. image:: https://img.shields.io/badge/-documentation-blue
+  :target: https://pydoctor.readthedocs.io/
+
 This is *pydoctor*, an API documentation generator that works by
 static analysis.
 
-It was written primarily to replace epydoc for the purposes of the
-Twisted project as epydoc has difficulties with zope.interface.
-If you are looking for a successor to epydoc after moving to Python 3,
-pydoctor might be the right tool for your project as well.
+It was written primarily to replace ``epydoc`` for the purposes of the
+Twisted project as ``epydoc`` has difficulties with ``zope.interface``.
+If you are looking for a successor to ``epydoc`` after moving to Python 3,
+``pydoctor`` might be the right tool for your project as well.
 
-pydoctor puts a fair bit of effort into resolving imports and
+``pydoctor`` puts a fair bit of effort into resolving imports and
 computing inheritance hierarchies and, as it aims at documenting
-Twisted, knows about zope.interface's declaration API and can present
+Twisted, knows about ``zope.interface``'s declaration API and can present
 information about which classes implement which interface, and vice
 versa.
 
 .. contents:: Contents:
 
 
-Usage
------
+Simple Usage
+~~~~~~~~~~~~
 
 You can run pydoctor on your project like this::
 
     $ pydoctor --make-html --html-output=docs/api --add-package=src/mylib
 
-You can see the full list of options using ``pydoctor --help``.
+For more info, `Read The Docs <https://pydoctor.readthedocs.io/>`_.
 
 Markup
-------
+~~~~~~
 
 pydoctor currently supports the following markup languages in docstrings:
 
 `epytext`__ (default)
     The markup language of epydoc.
     Simple and compact.
 
-`reStructuredText`__
+`restructuredtext`__
     The markup language used by Sphinx.
     More expressive than epytext, but also slighly more complex and verbose.
 
-plain text
+plaintext
     Text without any markup.
 
 __ http://epydoc.sourceforge.net/manual-epytext.html
 __ https://docutils.sourceforge.io/rst.html
 
 You can select a different format using the ``--docformat`` option.
 
-Sphinx Integration
-------------------
-
-Sphinx object inventories can be used to create deep links between API
-documentation generated by pydoctor and by Sphinx.
-
-Linking to external API docs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To link to the Python standard library documentation, add this to your
-pydoctor command line::
-
-    --intersphinx=https://docs.python.org/3/objects.inv
-
-You can pass this option multiple times to also link to other libraries
-that provide a Sphinx objects inventory.
-
-Linking to your API docs
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-pydoctor's HTML generator will also generate a Sphinx objects inventory
-using the following mapping:
-
-* packages, modules -> py:mod:
-* classes -> py:class:
-* functions -> py:func:
-* methods -> py:meth:
-* attributes -> py:attr:
-
-To use this mapping in Sphinx, configure the `intersphinx extension`__::
-
-    intersphinx_mapping = {
-        'pydoctor': ('http://domain.tld/api', None),
-    }
-
-__ https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
-
-And use external references::
-
-    :py:func:`External API <pydoctor:pydoctor.model.Documentable.reparent>`
-
-    :py:mod:`pydoctor:pydoctor`
-    :py:mod:`pydoctor:pydoctor.model`
-    :py:func:`pydoctor:pydoctor.driver.getparser`
-    :py:class:`pydoctor:pydoctor.model.Documentable`
-    :py:meth:`pydoctor:pydoctor.model.Documentable.reparent`
-    :py:attr:`pydoctor:pydoctor.model.Documentable.kind`
-
 What's New?
------------
+~~~~~~~~~~~
 
 pydoctor 20.7.2
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 * Fix handling of external links in reStructuredText under Python 3
 * Fix reporting of errors in reStructuredText under Python 3
 * Restore syntax highlighting of Python code blocks
 
 pydoctor 20.7.1
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 * Fix cross-reference links to builtin types in standard library
 * Fix and improve error message printed for unknown fields
 
 pydoctor 20.7.0
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 * Python 3 support
 * Type annotations on attributes are supported when running on Python 3
@@ -135,13 +90,3 @@ pydoctor 20.7.0
 This will be the last major release to support Python 2.7 and 3.5: future major releases will require Python 3.6 or later.
 
 .. description-end
-
-Releasing a new package
------------------------
-
-Releasing a new version is done via Travis-CI.
-First commit the version update to master and wait for tests to pass.
-Create a tag on local branch and then push it::
-
-    git tag 1.2.3
-    git push --tags

doc/fieldlist.txt

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/make.bat

@@ -0,0 +1,68 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'pydoctor'
+copyright = '2020, Michael Hudson-Doyle and various contributors (see Git history)'
+author = 'Michael Hudson-Doyle and various contributors (see Git history)'
+
+from pydoctor._version import __version__
+version = __version__.short()
+
+# -- General configuration ---------------------------------------------------
+
+# 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_rtd_theme", "sphinx.ext.intersphinx"
+]
+
+# 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 = []
+
+# Configure intersphinx magic
+intersphinx_mapping = {
+    'pydoctor': ('https://pydoctor.readthedocs.io/api/', None),
+    'twisted': ('https://twistedmatrix.com/documents/current/api/', None),
+}
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+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']
+
+# -- Automatically generate the Full help text in Shpinx build ---------------
+import pathlib
+import subprocess
+subprocess.run(
+    ["pydoctor", "--help"],
+    stdout=(pathlib.Path(__file__).parent / "help.txt").open('w')
+)

docs/source/conf.py

@@ -1,3 +1,11 @@
+Contribute
+==========
+
+.. include:: ../../CONTRIBUTING.rst
+
+Design Notes
+------------
+
 I guess I've always been interested in more-or-less static analysis of
 Python code and have over time developed some fairly strong opinions
 on the Right Way (tm) to do it.
@@ -20,3 +28,4 @@ Finally, pydoctor should never crash, no matter what code you feed it
 that universally applied, it seems).  Missing information is OK,
 crashing out is not.  This probably isn't as true as it should be at
 the moment.
+