Initial code.

Author: adiroiban

.gitignore

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

docs/source/conf.py

@@ -30,7 +30,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx_rtd_theme", "sphinx.ext.intersphinx"
+    "sphinx_rtd_theme",
+    "sphinx.ext.intersphinx",
+    "pydoctor.sphinx_ext.help_output",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -43,7 +45,7 @@
 
 # Configure intersphinx magic
 intersphinx_mapping = {
-    'pydoctor': ('https://pydoctor.readthedocs.io/api/', None),
+    #'pydoctor': ('https://pydoctor.readthedocs.io/api/', None),
     'twisted': ('https://twistedmatrix.com/documents/current/api/', None),
 }
 
@@ -57,12 +59,4 @@
 # 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')
-)
+html_static_path = []

docs/source/help.rst

@@ -1,4 +1,6 @@
-Full help
-=========
+Command line options
+====================
 
-.. include:: help.txt
+Below are the available command line options.
+
+.. help_output::

docs/source/usage.rst

@@ -6,8 +6,8 @@ Usage
 Most common options
 -------------------
 
-The following exemple uses all most common options to generate ``pydoctor``'s own API docs under the ``docs/api`` folder. 
-It will add a link to the project website in all pages header, show a link to source code aside every documented elements and resolve links to standard library objects. 
+The following exemple uses all most common options to generate ``pydoctor``'s own API docs under the ``docs/api`` folder.
+It will add a link to the project website in all pages header, show a link to source code aside every documented elements and resolve links to standard library objects.
 
 ::
 
@@ -22,12 +22,12 @@ It will add a link to the project website in all pages header, show a link to so
         --docformat=epytext \
         --intersphinx=https://docs.python.org/3/objects.inv
 
-.. note:: This exemple assume that you have cloned and installed ``pydoctor`` and you are running the ``pydoctor`` build from Unix and the current directory is the root folder of the Python project. 
+.. note:: This exemple assume that you have cloned and installed ``pydoctor`` and you are running the ``pydoctor`` build from Unix and the current directory is the root folder of the Python project.
 
-.. warning:: The ``--html-viewsource-base`` argument  should point to a tag or a commit SHA rather than a branch since line 
+.. warning:: The ``--html-viewsource-base`` argument  should point to a tag or a commit SHA rather than a branch since line
     numbers aren't going to match otherwise when commits are added to the branch after the documentation has been published.
 
-Publish your documentation 
+Publish your documentation
 --------------------------
 
 ``pydoctor`` output are static HTML pages without no extra server-side support.
@@ -84,8 +84,8 @@ Here is an exemple to automatically generate and publish your documentation with
             publish_dir: ./apidocs
             commit_message: "Generate pydoctor documentation"
 
-.. note:: As mentionned in the ``actions-gh-pages`` `documentation`__, the first workflow run won't actually publish the documentation to Github pages. 
-    Github pages needs to be enabled afterwards in the repo settings, select ``gh-pages`` branch, then re-run your workflow. 
+.. note:: As mentionned in the ``actions-gh-pages`` `documentation`__, the first workflow run won't actually publish the documentation to Github pages.
+    Github pages needs to be enabled afterwards in the repo settings, select ``gh-pages`` branch, then re-run your workflow.
 
     The website we'll be at https://(user).github.io/(repo)/
 
@@ -99,16 +99,16 @@ Here is an exemple to automatically generate and publish your documentation with
 Document part of your package
 -----------------------------
 
-Sometimes, only a couple classes or modules are part of your public API, not all classes and modules need to be documented.  
+Sometimes, only a couple classes or modules are part of your public API, not all classes and modules need to be documented.
 
 You can choose to document only a couple classes or modules with the following cumulative configuration option::
 
   --html-subject=pydoctor.zopeinterface.ZopeInterfaceSystem
 
-This will generate only ``pydoctor.zopeinterface.ZopeInterfaceSystem.html`` and ``objects.inv`` (and CSS and JS files of course). 
-The ``--add-package`` argument still needs to be passed, ``--html-subject`` will act like a filter.  
+This will generate only ``pydoctor.zopeinterface.ZopeInterfaceSystem.html`` and ``objects.inv`` (and CSS and JS files of course).
+The ``--add-package`` argument still needs to be passed, ``--html-subject`` will act like a filter.
 
-.. warning:: The ``index.html`` and other index files won't be generated, you need to link to the specific HTML page. 
+.. warning:: The ``index.html`` and other index files won't be generated, you need to link to the specific HTML page.
 
 Sphinx Integration
 ------------------
@@ -150,7 +150,7 @@ __ https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 
 Link to elements :py:func:`with custom text <twisted:twisted.web.client.urlunparse>` with::
 
-    :py:func:`with custom text <twisted:twisted.web.client.urlunparse>` 
+    :py:func:`with custom text <twisted:twisted.web.client.urlunparse>`
 
 Link to elements with default label :py:class:`twisted:twisted.web.client.HTTPDownloader` with::
 
@@ -179,7 +179,7 @@ You can subclass the :py:class:`pydoctor:pydoctor.zopeinterface.ZopeInterfaceSys
 
   --system-class=mylib._pydoctor.CustomSystem
 
-System class allows you to dynamically show/hide classes or methods. 
+System class allows you to dynamically show/hide classes or methods.
 This is also used by the Twisted project to handle deprecation.
 
 See the `Twisted custom class documentation <https://twistedmatrix.com/documents/current/api/twisted.python._pydoctor.TwistedSystem.html>`_. Naviguate to the source code for a better overview.
@@ -192,7 +192,7 @@ Use custom HTML templates
 Currently, custom HTLM templates needs to be handled with some "monkeypatch" that will selectively use the appropriate templates.
 
 See the `Twisted custom class documentation <https://twistedmatrix.com/documents/current/api/twisted.python._release.APIBuilder.html>`_. Naviguate to the source code for a better overview.
-The key thing is to apply a patch to the :py:func:`pydoctor:pydoctor.templatewriter.util.templatefile` function before the build. 
+The key thing is to apply a patch to the :py:func:`pydoctor:pydoctor.templatewriter.util.templatefile` function before the build.
 
 .. note:: Not fully documented, prone to break
 
@@ -203,4 +203,4 @@ You can subclass the :py:class:`pydoctor:pydoctor.templatewriter.writer.Template
 
   --html-writer=mylib._pydoctor.CustomTemplateWriter
 
-.. note:: Not fully documented, prone to break
+.. note:: Not fully documented, prone to break

pydoctor/driver.py

@@ -365,6 +365,10 @@ def p(msg):
                 for fn in sorted(system.docstring_syntax_errors):
                     p('    '+fn)
 
+            if system.warnings:
+                # Update exit code if the run has produced warnings.
+                exitcode = 1
+
         if options.makeintersphinx:
             if not options.makehtml:
                 subjects = system.rootobjects
@@ -384,4 +388,5 @@ def p(msg):
             import pdb
             pdb.post_mortem(sys.exc_info()[2])
         raise
+
     return exitcode

pydoctor/sphinx_ext/__init__.py

@@ -0,0 +1,39 @@
+"""
+Produce the pydoctor help output to be included in the documentation.
+"""
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+from contextlib import redirect_stdout
+from io import StringIO
+from pydoctor.driver import parse_args
+
+
+class HelpOutputDirective(SphinxDirective):
+
+    # this enables content in the directive
+    has_content = True
+
+    def run(self):
+
+        stream = StringIO()
+        try:
+            with redirect_stdout(stream):
+                parse_args(['--help'])
+        except SystemExit:
+            pass
+
+        text = ['pydoctor --help'] + stream.getvalue().splitlines()[1:]
+        return [nodes.literal_block(text='\n'.join(text))]
+
+
+def setup(app):
+    app.add_directive('help_output', HelpOutputDirective)
+
+    return {
+            'version': '0.1',
+            'parallel_read_safe': True,
+            'parallel_write_safe': True,
+        }
+
+

pydoctor/sphinx_ext/help_output.py

@@ -68,3 +68,31 @@ commands =
         --cache-dir="{toxworkdir}/mypy_cache"  \
         {tty:--pretty:}                        \
         {posargs:pydoctor}
+
+
+[testenv:apidocs]
+description = Build only the API documentation
+
+whitelist_externals =
+    cat
+    test
+commands =
+    pydoctor \
+    --add-package=pydoctor \
+    --project-name=pydoctor \
+    --project-url=https://github.com/twisted/pydoctor/ \
+    --html-viewsource-base=https://github.com/twisted/pydoctor/tree/20.7.2 \
+    --html-output=build/apidocs \
+    --project-base-dir="{toxinidir}" \
+    --docformat=epytext \
+    --intersphinx=https://docs.python.org/3/objects.inv \
+    --make-html
+
+
+[testenv:docs]
+description = Build the full documentation
+
+extras = docs
+
+commands =
+    sphinx-build -aE -b html {toxinidir}/docs/source {toxinidir}/build/docs