From 7230330686a2f5a8314e9d96e52d3a570bc821ba Mon Sep 17 00:00:00 2001 From: Ashley Whetter Date: Sat, 6 Apr 2019 17:56:05 -0700 Subject: [PATCH] Documentation overhaul --- CHANGELOG.rst | 152 +++++++++++++++ LICENSE.mit => LICENSE.rst | 3 + README.rst | 267 +++++++++------------------ autoapi/mappers/base.py | 2 +- autoapi/mappers/python/objects.py | 97 +++++++++- docs/Makefile | 195 ------------------- docs/conf.py | 11 +- docs/config.rst | 117 ------------ docs/how_to.rst | 86 +++++++++ docs/index.rst | 12 +- docs/{ => maintenance}/design.rst | 23 ++- docs/maintenance/release-process.rst | 30 +++ docs/reference/config.rst | 147 +++++++++++++++ docs/{ => reference}/directives.rst | 12 +- docs/reference/templates.rst | 98 ++++++++++ docs/templates.rst | 41 ---- docs/tutorials.rst | 232 +++++++++++++++++++++++ setup.py | 19 +- tests/goexample/Makefile | 195 ------------------- tests/jsexample/Makefile | 195 ------------------- tests/python/pyexample/Makefile | 195 ------------------- tests/templateexample/Makefile | 195 ------------------- tests/toctreeexample/Makefile | 195 ------------------- tox.ini | 4 +- 24 files changed, 998 insertions(+), 1525 deletions(-) create mode 100644 CHANGELOG.rst rename LICENSE.mit => LICENSE.rst (95%) delete mode 100644 docs/Makefile delete mode 100644 docs/config.rst create mode 100644 docs/how_to.rst rename docs/{ => maintenance}/design.rst (89%) create mode 100644 docs/maintenance/release-process.rst create mode 100644 docs/reference/config.rst rename docs/{ => reference}/directives.rst (74%) create mode 100644 docs/reference/templates.rst delete mode 100644 docs/templates.rst create mode 100644 docs/tutorials.rst delete mode 100644 tests/goexample/Makefile delete mode 100644 tests/jsexample/Makefile delete mode 100644 tests/python/pyexample/Makefile delete mode 100644 tests/templateexample/Makefile delete mode 100644 tests/toctreeexample/Makefile diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 0000000..75d9b80 --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1,152 @@ +Changelog +========= + +Versions follow `Semantic Versioning `_ (``..``). + +vTBC +---- + +Features +~~~~~~~~ + +* `#100 `: (Python) Added support for documenting C extensions via ``.pyi`` stub files. +* Added support for Sphinx 2.0. +* Toned down the API reference index page. +* (Go) Patterns configured in ``autoapi_ignore`` are passed to godocjson. + +Bug Fixes +~~~~~~~~~ + +* `#159 `: (Python) Fixed ``UnicodeDecodeError`` on Python 2 when a documenting an attribute that contains binary data. +* (Python) Fixed private submodules displaying when ``private-members`` is turned off. +* Templates no longer produce excessive whitespace. + +Trivial/Internal Changes +~~~~~~~~~~~~~~~~~~~~~~~~ + +* No longer pin the version of black. +* Added missing test environments to travis. + + +v0.7.1 (2019-02-04) +------------------- + +Bug Fixes +~~~~~~~~~ + +* (Python) Fixed a false warning when importing a local module. + + +v0.7.0 (2019-01-30) +------------------- + +Breaking Changes +~~~~~~~~~~~~~~~~ + +* Dropped support for Sphinx<1.6. + +Features +~~~~~~~~ + +* Added debug messages about what AutoAPI is doing. + +Bug Fixes +~~~~~~~~~ + +* `#156 `: (Python) Made import resolution more stable. + + Also capable of giving more detailed warnings. + + +Trivial/Internal Changes +~~~~~~~~~~~~~~~~~~~~~~~~ + +* Code is now formatted using black. +* Removed references to old css and js files. +* Replaced usage of deprecated Sphinx features. +* Reorganised tests to be more pytest-like. + + +v0.6.2 (2018-11-15) +------------------- + +Bug Fixes +~~~~~~~~~ + +* (Python) Fixed some import chains failing to resolve depending on resolution order. + + +v0.6.1 (2018-11-14) +------------------- + +Bug Fixes +~~~~~~~~~ + +* (Python) Fixed unicode decoding on Python 3.7. +* (Python) Fixed autodoc directives not documenting anything in submodules or subpackages. +* (Python) Fixed error parsing files with unicode docstrings. +* (Python) Fixed error when documenting something that's imported in more than one place. + + +Trivial/Internal Changes +~~~~~~~~~~~~~~~~~~~~~~~~ + +* (Python) Added Python 3.7 testing. +* Started testing against stable version of Sphinx 1.8. +* Fixed all "no title" warnings during tests. + + +v0.6.0 (2018-08-20) +------------------- + +Breaking Changes +~~~~~~~~~~~~~~~~ + +* `#152 `: Removed the ``autoapi_add_api_root_toctree`` option. + + This has been replaced with the ``autoapi_add_toctree_entry`` option. + +* `#25 `: Removed distutils support. +* Removed redundant ``package_dir`` and ``package_data`` options. + +Features +~~~~~~~~ + +* (Python) Added viewcode support for imported members. +* `#146 `: (Python) No longer documents ``__init__()`` attributes without a docstring. +* `#153 `: (Python) Can document a public python API. +* `#111 `: (Python) Can opt to write manual documentation through new autodoc-style directives. +* `#152 `: Made it easier to remove default index page. + + Also removed autoapi_add_api_root_toctree config option + +* `#150 `: (Python) ``private-members`` also controls private subpackages and submodules. +* (Python) Added support for static and class methods. +* (Python) Methods include ``self`` in their arguments. + + This more closely matches autodoc behaviour. + +* `#145 `: (Python) Added support for detecting Python exceptions. +* (Python) Can control how __init__ docstring is displayed. +* (Python) Added support for viewcode. +* (Python) Source files no longer need to be in ``sys.path``. + +Bug Fixes +~~~~~~~~~ + +* (Python) Fixed linking to builtin bases. +* (Python) Fixed properties being documented more than once when set in ``__init__()``. +* (Python) Fixed nested classes not getting displayed. +* `#148 `: (Python) Fixed astroid 2.0 compatibility. +* (Python) Fixed filtered classes and attributes getting displayed. +* (Python) Fixed incorrect display of long lists. +* `#125 `: (Javacript) Fixed running incorrect jsdoc command on Windows. +* `#125 `: (Python) Support specifying package directories in ``autoapi_dirs``. + +Trivial/Internal Changes +~~~~~~~~~~~~~~~~~~~~~~~~ + +* Added Sphinx 1.7 and 1.8.0b1 testing. +* `#120 `: Updated documentation to remove outdated references. +* Removed old testing dependencies. +* `#143 `: Removed unnecessary wheel dependency. diff --git a/LICENSE.mit b/LICENSE.rst similarity index 95% rename from LICENSE.mit rename to LICENSE.rst index 037d356..991c700 100644 --- a/LICENSE.mit +++ b/LICENSE.rst @@ -1,3 +1,6 @@ +The MIT License (MIT) +===================== + Copyright (c) 2015 Read the Docs, Inc Permission is hereby granted, free of charge, to any person diff --git a/README.rst b/README.rst index 77d25ed..dd013db 100644 --- a/README.rst +++ b/README.rst @@ -2,235 +2,138 @@ Sphinx AutoAPI ============== .. image:: https://readthedocs.org/projects/sphinx-autoapi/badge/?version=latest - :target: https://sphinx-autoapi.readthedocs.org - :alt: Documentation Status + :target: https://sphinx-autoapi.readthedocs.org + :alt: Documentation .. image:: https://travis-ci.org/rtfd/sphinx-autoapi.svg?branch=master - :target: https://travis-ci.org/rtfd/sphinx-autoapi + :target: https://travis-ci.org/rtfd/sphinx-autoapi + :alt: Travis Build Status .. image:: https://ci.appveyor.com/api/projects/status/5nd33gp2eq7411t1?svg=true - :target: https://ci.appveyor.com/project/ericholscher/sphinx-autoapi + :target: https://ci.appveyor.com/project/ericholscher/sphinx-autoapi + :alt: Appveyor Build Status -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/ambv/black - -.. warning:: This is a pre-release version. Some or all features might not work yet. - -Sphinx AutoAPI aims to provide "autodoc" or "javadoc" style documentation for Sphinx. -The aim is to support all programming languages, -be easy to use, -and not require much configuration. - -AutoAPI is a parse-only solution for both static and dynamic languages. -This is in contrast to the traditional `Sphinx autodoc `_, -which is Python-only and uses code imports. - -Full documentation can be found on `Read the Docs `_. +.. image:: https://img.shields.io/pypi/v/sphinx-autoapi.svg + :target: https://pypi.org/project/sphinx-autoapi/ + :alt: PyPI Version -Contents --------- +.. image:: https://img.shields.io/pypi/pyversions/sphinx-autoapi.svg + :target: https://pypi.org/project/sphinx-autoapi/ + :alt: Supported Python Versions -.. toctree:: - :caption: Main - :glob: - :maxdepth: 2 - - config - templates +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/ambv/black + :alt: Formatted with Black -.. toctree:: - :caption: API - :glob: - :maxdepth: 2 +Sphinx AutoAPI provides "autodoc" style documentation for multiple programming languages +without needing to load, run, or import the project being documented. - design - directives +In contrast to the traditional `Sphinx autodoc `_, +which is Python-only and uses code imports, +AutoAPI finds and generates documentation by parsing source code. +Language Support +---------------- -Basic Workflow --------------- +========== ====== ========================================================== +Language Status Parser +========== ====== ========================================================== +Python Stable Custom using `astroid `_ +Go Alpha `godocjson `_ +Javascript Alpha `jsdoc `_ +.NET Alpha `docfx `_ +========== ====== ========================================================== -Sphinx AutoAPI has the following structure: +Getting Started +--------------- -* Configure directory to look for source files -* Serialize those source files, using language-specific tooling -* Map the serialized data into standard AutoAPI Python objects -* Generate RST through Jinja2 templates from those Python objects +The following steps will walk through how to add AutoAPI to an existing Sphinx project. +For instructions on how to set up a Sphinx project, +see Sphinx's documentation on +`Getting Started `_. -This basic framework should be easy to implement in your language of choice. -All you need to do is be able to generate a JSON structure that includes your API and docs for those classes, functions, etc. +Installation +~~~~~~~~~~~~ -Install -------- +AutoAPI can be installed through pip: -First you need to install autoapi: - -.. code:: bash +.. code-block:: bash pip install sphinx-autoapi -Then add it to your Sphinx project's ``conf.py``: +Next, add and configure AutoAPI in your Sphinx project's `conf.py`. +Other languages may require +[further configuration](https://sphinx-autoapi.readthedocs.io/en/latest/tutorials.html#setting-up-automatic-api-documentation-generation): -.. code:: python +.. code-block:: python - extensions = ['autoapi.extension'] + extensions.append('autoapi.extension') - # Document Python Code autoapi_type = 'python' - autoapi_dirs = ['path/to/python/files', 'path/to/more/python/files'] - - # Or, Document Go Code - autoapi_type = 'go' - autoapi_dirs = 'path/to/go/files' - -AutoAPI will automatically add itself to the last TOCTree in your top-level -``index.rst``. - -This is needed because we will be outputting rst files into the ``autoapi`` -directory. This adds it into the global TOCTree for your project, so that it -appears in the menus. - -We hope to be able to dynamically add items into the TOCTree, and remove this -step. However, it is currently required. - -See all available configuration options in :doc:`config`. - -Setup ------ - -.NET -~~~~ - -The .NET mapping utilizes the tool `docfx`_. To install ``docfx``, first -you'll need to `install a .NET runtime on your system `_. - -The docfx tool can be installed with:: - - dnu commands install docfx - -By default, ``docfx`` will output metadata files into the ``_api`` path. You -can configure which path to output files into by setting the path in your -`docfx configuration file`_ in your project's repository. For example: + autoapi_dirs = ['path/to/source/files', 'src'] -.. code:: json +Where `autoapi_type` can be one of any of the supported languages: - { - ... - "metadata": [{ - ... - "dest": "docs/_api", - ... - }] - } +========== ================ +Language ``autoapi_type`` +========== ================ +Python ``'python'`` +Go ``'go'`` +Javascript ``'javascript'`` +.NET ``'dotnet'`` +========== ================ -.. note:: - The ``dest`` configuration option is required to output to the ``docs/`` - path, where autoapi knows to search for these files. +When the documentation is built, +AutoAPI will now generate API documentation into an `autoapi/` directory and add an entry to the documentation in your top level table of contents! -With a working ``docfx`` toolchain, you can now add the configuration options -to enable the .NET autoapi mapper. In your ``conf.py``: +To configure AutoAPI behaviour further, +see the `Configuration documentation `_. -.. code:: python - extensions = ['autoapi.extension'] - autoapi_type = 'dotnet' - autoapi_dirs = ['..'] +Contributing +------------ -This configuration assumes your ``conf.py`` is in a ``docs/`` path, and will use -your parent path ('..') to search for files to pass to ``docfx``. Unless you -specify a custom pattern, using the ``autoapi_patterns`` option, -``sphinx-autoapi`` will assume a list of file names to search. +Running the tests +~~~~~~~~~~~~~~~~~ -First, a ``docfx.json`` file will be searched for. If this file exists, it will -be used, regardless of whether you have other file patterns listed. Otherwise, -any file matching ``['project.json', 'csproj', 'vsproj']`` will be searched for. +Tests are executed through `tox `_. -.. _`docfx`: https://github.com/dotnet/docfx -.. _`ASP.NET Installation`: http://docs.asp.net/en/latest/getting-started/index.html -.. _`docfx configuration file`: https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#3-docfx-json-format +.. code-block:: bash + tox -GO -~~~~ +Code Style +~~~~~~~~~~ -Install go domain extension for sphinx. +Code is formatted using `black `_. -.. code:: bash +You can check your formatting using black's check mode: - pip install go sphinxcontrib_golangdomain +.. code-block:: bash + tox -e formatting -Install the go environment (from https://golang.org/dl/). +You can also get black to format your changes for you: -Install a git client for your environment (e.g. from https://desktop.github.com/). +.. code-block:: bash -Install our godocjson tool (preprocess godoc output to JSON, in a way similar to jsdoc -X). + black autoapi/ tests/ -.. code:: bash +You can even get black to format changes automatically when you commit using `pre-commit `_: - go get github.com/rtfd/godocjson -Add go domain in your conf.py. +.. code-block:: bash -.. code:: python + pip install pre-commit + pre-commit install - extensions = [ 'sphinxcontrib.golangdomain',... - -Before running building your doc, make sure the godocjson executable is in your path. - -Javascript -~~~~~~~~~~~~~~~~ - -Requires jsdoc, which in turn requires nodejs to be installed. - -Install nodejs on your platform. - -Install jsdoc using npm. - -.. code:: bash - - npm install jsdoc -g - -Before building your doc, make sure the jsdoc executable is in your path. - - -Customize ---------- - -All of the pages that AutoAPI generates are templated with Jinja2 templates. -You can fully customize how pages are displayed on a per-object basis. -Read more about it in :doc:`templates`. - -Directives +Versioning ---------- -Instead of generating API documentation, -you can write the documentation yourself with :doc:`directives`. - -Design ------- - -Read more about the deisgn in our :doc:`design`. - -Currently Implemented ---------------------- +We use `SemVer `_ for versioning. For the versions available, see the `tags on this repository `_. -* Python (2.7+ and 3.4+) -* .NET -* Go -* Javascript - -Adding a new language ---------------------- - -Adding a new language should only take a couple of hours, -assuming your language has a tool to generate JSON from API documentation. - -The steps to follow: - -* Add a new Mapper file in `mappers/`. It's probably easiest to copy an existing one, like the Javascript or Python mappers. -* Implement the :py:func:`create_class` and :py:func:`read_file` methods on the :py:class:`SphinxMapperBase`. -* Implement all appropriate object types on the :py:class:`PythonMapperBase` -* Add a test in the `tests/test_integration.py`, along with an example project for the testing. -* Include it in the class mapping in `mappers/base.py` and `extension.py` +License +------- +This project is licensed under the MIT License. +See the `LICENSE.rst ` file for details. diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py index 9f711e0..383c4cd 100644 --- a/autoapi/mappers/base.py +++ b/autoapi/mappers/base.py @@ -83,7 +83,7 @@ class PythonMapperBase(object): @property def rendered(self): - "Shortcut to render an object in templates." + """Shortcut to render an object in templates.""" return self.render() def get_absolute_path(self): diff --git a/autoapi/mappers/python/objects.py b/autoapi/mappers/python/objects.py index 230162f..03cc999 100644 --- a/autoapi/mappers/python/objects.py +++ b/autoapi/mappers/python/objects.py @@ -4,6 +4,15 @@ from ..base import PythonMapperBase class PythonPythonMapper(PythonMapperBase): + """A base class for all types of representations of Python objects. + + :var name: The name given to this object. + :vartype name: str + :var id: A unique identifier for this object. + :vartype id: str + :var children: The members of this object. + :vartype children: list(PythonPythonMapper) + """ language = "python" is_callable = False @@ -20,11 +29,17 @@ class PythonPythonMapper(PythonMapperBase): self.docstring = obj["doc"] # For later - self.item_map = collections.defaultdict(list) self._class_content = class_content @property def args(self): + """The arguments to this object, formatted as a string. + + This will only be set for a function, method, or class. + For classes, this does not include ``self``. + + :type: str or None + """ return self._args @args.setter @@ -33,6 +48,16 @@ class PythonPythonMapper(PythonMapperBase): @property def docstring(self): + """The docstring for this object. + + If a docstring did not exist on the object, + this will be the empty string. + + For classes this will also depend on the + :confval:`autoapi_python_class_content` option. + + :type: str + """ return self._docstring @docstring.setter @@ -41,18 +66,37 @@ class PythonPythonMapper(PythonMapperBase): @property def is_undoc_member(self): + """Whether this object has a docstring (False) or not (True). + + :type: bool + """ return not bool(self.docstring) @property def is_private_member(self): + """Whether this object is private (True) or not (False). + + :type: bool + """ return self.short_name.startswith("_") and not self.short_name.endswith("__") @property def is_special_member(self): + """Whether this object is a special member (True) or not (False). + + :type: bool + """ return self.short_name.startswith("__") and self.short_name.endswith("__") @property def display(self): + """Whether this object should be displayed in documentation. + + This attribute depends on the configuration options given in + :confval:`autoapi_options`. + + :type: bool + """ if self.is_undoc_member and "undoc-members" not in self.options: return False if self.is_private_member and "private-members" not in self.options: @@ -63,6 +107,13 @@ class PythonPythonMapper(PythonMapperBase): @property def summary(self): + """The summary line of the docstring. + + The summary line is the first non-empty line, as-per :pep:`257`. + This will be the empty string if the object does not have a docstring. + + :type: str + """ for line in self.docstring.splitlines(): line = line.strip() if line: @@ -89,9 +140,22 @@ class PythonMethod(PythonPythonMapper): super(PythonMethod, self).__init__(obj, **kwargs) self.method_type = obj["method_type"] + """The type of method that this object represents. + + This can be one of: method, staticmethod, or classmethod. + + :type: str + """ @property def display(self): + """Whether this object should be displayed in documentation. + + This attribute depends on the configuration options given in + :confval:`autoapi_options`. + + :type: bool + """ if self.short_name == "__init__": return False @@ -107,6 +171,12 @@ class PythonData(PythonPythonMapper): super(PythonData, self).__init__(obj, **kwargs) self.value = obj.get("value") + """The value of this attribute. + + This will be ``None`` if the value is not constant. + + :type: str or None + """ class PythonAttribute(PythonData): @@ -123,17 +193,38 @@ class TopLevelPythonPythonMapper(PythonPythonMapper): super(TopLevelPythonPythonMapper, self).__init__(obj, **kwargs) self.top_level_object = "." not in self.name + """Whether this object is at the very top level (True) or not (False). + + This will be False for subpackages and submodules. + + :type: bool + """ self.subpackages = [] self.submodules = [] self.all = obj["all"] + """The contents of ``__all__`` if assigned to. + + Only constants are included. + This will be ``None`` if no ``__all__`` was set. + + :type: list(str) or None + """ @property def functions(self): + """All of the member functions. + + :type: list(PythonFunction) + """ return self._children_of_type("function") @property def classes(self): + """All of the member classes. + + :type: list(PythonClass) + """ return self._children_of_type("class") @@ -152,6 +243,10 @@ class PythonClass(PythonPythonMapper): super(PythonClass, self).__init__(obj, **kwargs) self.bases = obj["bases"] + """The fully qualified names of all base classes. + + :type: list(str) + """ @PythonPythonMapper.args.getter def args(self): diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 00ed77f..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/conf.py b/docs/conf.py index c47e3ed..b47a651 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,15 +20,16 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['autoapi.extension'] +extensions = ['autoapi.extension', 'sphinx.ext.intersphinx'] autoapi_type = 'python' autoapi_dirs = ['../autoapi'] -autoapi_file_pattern = '*.py' -autoapi_options = ['members', 'undoc-members', 'private-members'] +autoapi_generate_api_docs = False -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +intersphinx_mapping = { + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), + 'python': ('https://docs.python.org/3/', None), +} # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: diff --git a/docs/config.rst b/docs/config.rst deleted file mode 100644 index 02c6aa7..0000000 --- a/docs/config.rst +++ /dev/null @@ -1,117 +0,0 @@ -AutoAPI Configuration -===================== - -Configuration Options ---------------------- - -.. confval:: autoapi_dirs - - **Required** - - Paths (relative or absolute) to the source code that you wish to generate your API documentation from. - - If a package directory is specified, the package directory itself will be included in the relative path of the - children. If an ordinary directory is specified, that directory will not be included in the relative path. - -.. confval:: autoapi_type - - Default: ``python`` - - Set the type of files you are documenting - -.. confval:: autoapi_template_dir - - Default: ``''`` - - A directory that has user-defined templates to override our default templates. - - You can see the existing files in the `autoapi_templates`_ directory. - -.. confval:: autoapi_file_patterns - - Default: ``Varies by Language`` - - A list containing the file patterns to look for when generating documentation. Python for example is ``['*.py']``. - -.. confval:: autoapi_generate_api_docs - - Default: ``True`` - - Whether to generate API documentation. - If this is ``False``, documentation should be generated though the - :doc:`directives`. - - -Customization Options ---------------------- - -.. confval:: autoapi_options - - Default: ``['members', 'undoc-members', 'private-members', 'special-members']`` - - Options for display of the documentation. - - :param members: Display children of an object - :param undoc-members: Display undocumented object - :param private-members: Display private objects (_foo in Python) - :param special-members: Display special objects (__foo__ in Python) - - -.. confval:: autoapi_ignore - - Default: ``[]`` - - A list of patterns to ignore when finding files - -.. confval:: autoapi_root - - Default: ``autoapi`` - - Relative path to output the AutoAPI files into. - This can also be used to place the generated documentation - anywhere in your documentation hierarchy. - -.. confval:: autoapi_add_toctree_entry - - Default: ``True`` - - Whether to insert the generated documentation into the toctree. - If this is False, the default AutoAPI index page is not generated. - You will also need to include the generated documentation - in a toctree entry yourself. - - This can be used with :confval:`autoapi_root` to place - the generated documentation somewhere other than the root. - -.. confval:: autoapi_include_summaries - - Default: ``False`` - - Whether include autosummary directives in generated module documentation. - -.. confval:: autoapi_python_class_content - - Default: ``class`` - - Which docstring to insert into the content of the class. - - :param class: Use only the class docstring. - :param both: Use the concatentation of the class docstring and the - ``__init__``/``__new__`` docstring. - :param init: Use only the ``__init__``/``__new__`` docstring. - - If the class does not have an ``__init__`` or the ``__init__`` - docstring is empty and the class defines a ``__new__`` with a docstring, - the ``__new__`` docstring is used instead of the ``__init__`` docstring. - -Debugging Options ------------------ - -.. confval:: autoapi_keep_files - - Default: ``False`` - - Keep the AutoAPI generated files on the filesystem after the run. - Useful for debugging. - -.. _autoapi_templates: https://github.com/rtfd/sphinx-autoapi/tree/master/autoapi/templates diff --git a/docs/how_to.rst b/docs/how_to.rst new file mode 100644 index 0000000..fd6b9dd --- /dev/null +++ b/docs/how_to.rst @@ -0,0 +1,86 @@ +How-to Guides +============= + +.. _customise-templates: + +How to Customise Layout Through Templates +----------------------------------------- + +You can customise the look of the documentation that AutoAPI generates +by changing the Jinja2 templates that it uses. +The default templates live in the ``autoapi/templates`` directory of the AutoAPI package. +Simply copy whichever templates you want to customise to a local directory +and edit them. +To get AutoAPI to use these templates, +point the :confval:`autoapi_template_dir` configuration option to your directory. +It can be absolute, or relative to where ``sphinx-build`` is run. + +.. code-block:: + + autoapi_template_dir = '_autoapi_templates' + + +How to Customise the Index Page +------------------------------- + +The index page that AutoAPI creates is generates using a template. +So customising the index page follows the same steps as customising a template. +Simply edit the ``autoapi/templates/index.rst`` template +with the same steps as :ref:`customising a template `. + + +How to Remove the Index Page +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To remove the index page altogether, +turn off the :confval:`autoapi_add_toctree_entry` configuration option:: + + autoapi_add_toctree_entry = False + +You will then need to include the generated documentation in the toctree yourself. +For example if you were generating documentation for a package called "example", +you would add the following toctree entry:: + + .. toctree:: + + autoapi/example/index + +Note that ``autoapi/`` is the default location of documentation, +as configured by :confval:`autoapi_root`. +If you change :confval:`autoapi_root`, +then the entry that you need to add would change also. + + +How to Configure Where Documentation Appears in the TOC Tree +------------------------------------------------------------ + +The :confval:`autoapi_root` configuration option defines where generated documentation is output. +To change where documentation is output, +simply change this option to another directory relative to the ``conf.py`` file: + +.. code-block:: python + + autoapi_root = 'technical/api' + + +How to Transition to Autodoc-Style Documentation +---------------------------------------------------- + +Once you have written some documentation with the :ref:`autodoc-directives`, +turning the automatic documentation generation off is as easy as +disabling the :confval:`autoapi_generate_api_docs` configuration option:: + + autoapi_generate_api_docs = False + + +How to Transition to Manual Documentation +----------------------------------------- + +To start writing API documentation yourself, +you can get AutoAPI to keep its generated files around as a base to start from +using he :confval:`autoapi_keep_files` option:: + + autoapi_keep_files = True + +Once you have built your documentation with this option turned on, +you can disable AutoAPI altogether from your project. diff --git a/docs/index.rst b/docs/index.rst index 72a3355..7c8c373 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1 +1,11 @@ -.. include:: ../README.rst +Sphinx AutoAPI +============== + +.. toctree:: + :maxdepth: 2 + :glob: + + tutorials + how_to + reference/* + maintenance/* diff --git a/docs/design.rst b/docs/maintenance/design.rst similarity index 89% rename from docs/design.rst rename to docs/maintenance/design.rst index 6723d3f..e5a6f88 100644 --- a/docs/design.rst +++ b/docs/maintenance/design.rst @@ -1,6 +1,25 @@ -Sphinx AutoAPI Reference Design -================================ +Design Reference +================ +Python +------ + +When choosing what to document, +AutoAPI aims to document anything that is accessible through the actual package +when loaded in Python. +For example if a function is imported from a submodule into a package, +that function is documented in both the submodule and the package. +There are some exceptions to this rule: + +* Anything that is imported into a module is not documented. + Usually a module is where implementations exist. + Therefore an import of something is usually for the usage of the implementation, + and not as something to be accessed publicly. + + + +.NET +---- This document talks about the design of a .NET Sphinx integration. This will include a mechanism for generating Javadoc style API references automatically. We will describe decisions that lead to specific implementation details. diff --git a/docs/maintenance/release-process.rst b/docs/maintenance/release-process.rst new file mode 100644 index 0000000..c4b3ee7 --- /dev/null +++ b/docs/maintenance/release-process.rst @@ -0,0 +1,30 @@ +Release Process +=============== + +This page documents the steps to be taken to release a new version of Sphinx AutoAPI. + +Pre-Checks +---------- + +1. Check that the dependencies of the package are correct. +2. Clean the ``.tox`` directory and run the tests. +3. Commit and push any changes needed to make the tests pass. +4. Check that the tests passed on travis and appveyor. + +Preparation +----------- + +1. Update the version number in ``setup.py`` and ``docs/conf.py``. +2. Add any missing changelog entries. +3. Put the version number and release date into the changelog. +4. Commit and push the changes. +5. Check that the tests passed on travis and appveyor. + +Release +------- + +.. code-block:: bash + + git clean -fdx + python setup.py sdist bdist_wheel + twine upload dist/* diff --git a/docs/reference/config.rst b/docs/reference/config.rst new file mode 100644 index 0000000..25aaadb --- /dev/null +++ b/docs/reference/config.rst @@ -0,0 +1,147 @@ +Configuration Options +===================== + +.. confval:: autoapi_dirs + + **Required** + + Paths (relative or absolute) to the source code that you wish to generate your API documentation from. + + For Python, if a package directory is specified, + the package directory itself will be included in the relative path of the children. + If an ordinary directory is specified, + that directory will not be included in the relative path. + +.. confval:: autoapi_type + + Default: ``python`` + + Set the type of files you are documenting. + This depends on the programming language that you are using: + + ========== ================ + Language ``autoapi_type`` + ========== ================ + Python ``'python'`` + Go ``'go'`` + Javascript ``'javascript'`` + .NET ``'dotnet'`` + ========== ================ + +.. confval:: autoapi_template_dir + + Default: ``''`` + + A directory that has user-defined templates to override our default templates. + + You can view the default templates in the + `autoapi/templates `_ + directory of the package. + +.. confval:: autoapi_file_patterns + + Default: Varies by Language + + A list containing the file patterns to look for when generating documentation. + The defaults by language are: + + ========== ============================================ + Language ``autoapi_file_patterns`` + ========== ============================================ + Python ``['*.py', '*.pyi']`` + Go ``['*.go']`` + Javascript ``['*.js']`` + .NET ``['project.json', '*.csproj', '*.vbproj']`` + ========== ============================================ + +.. confval:: autoapi_generate_api_docs + + Default: ``True`` + + Whether to generate API documentation. + If this is ``False``, documentation should be generated though the + :doc:`directives`. + + +Customization Options +--------------------- + +.. confval:: autoapi_options + + Default: ``['members', 'undoc-members', 'private-members', 'special-members']`` + + Options for display of the documentation. + + * ``members``: Display children of an object + * ``undoc-members``: Display objects that have no docstring + * ``private-members``: Display private objects (eg. ``_foo`` in Python) + * ``special-members``: Display special objects (eg. ``__foo__`` in Python) + +.. confval:: autoapi_ignore + + Default: Varies By Language + + A list of patterns to ignore when finding files + The defaults by language are: + + ========== ============================================ + Language ``autoapi_file_patterns`` + ========== ============================================ + Python ``['*migrations*']`` + Go ``[]`` + Javascript ``[]`` + .NET ``['*toc.yml', '*index.yml']`` + ========== ============================================ + +.. confval:: autoapi_root + + Default: ``autoapi`` + + Path to output the generated AutoAPI files into, + including the generated index page. + This path should be relative to the root of the documentation directory + (ie the directory with the ``conf.py`` file). + This can be used to place the generated documentation + anywhere in your documentation hierarchy. + +.. confval:: autoapi_add_toctree_entry + + Default: ``True`` + + Whether to insert the generated documentation into the TOC tree. + If this is ``False``, the default AutoAPI index page is not generated + and you will need to include the generated documentation + in a TOC tree entry yourself. + +.. confval:: autoapi_include_summaries + + Default: ``False`` + + Whether include autosummary directives in generated module documentation. + This is a shortcut for needing to edit the templates yourself. + +.. confval:: autoapi_python_class_content + + Default: ``class`` + + Which docstring to insert into the content of a class. + + * ``class``: Use only the class docstring. + * ``both``: Use the concatentation of the class docstring and the + ``__init__`` docstring. + * ``init``: Use only the ``__init__`` docstring. + + If the class does not have an ``__init__`` or the ``__init__`` + docstring is empty and the class defines a ``__new__`` with a docstring, + the ``__new__`` docstring is used instead of the ``__init__`` docstring. + + +Debugging Options +----------------- + +.. confval:: autoapi_keep_files + + Default: ``False`` + + Keep the AutoAPI generated files on the filesystem after the run. + Useful for debugging or transitioning to manual documentation. diff --git a/docs/directives.rst b/docs/reference/directives.rst similarity index 74% rename from docs/directives.rst rename to docs/reference/directives.rst index d4e1781..f225e8d 100644 --- a/docs/directives.rst +++ b/docs/reference/directives.rst @@ -1,9 +1,17 @@ +.. _autodoc-directives: + Autodoc-Style Directives ------------------------- +======================== You can opt to write API documentation yourself using autodoc style directives. These directives work similarly to autodoc, -but docstring are retrieved through static analysis instead of through imports. +but docstrings are retrieved through static analysis instead of through imports. + +.. seealso:: + + When transitioning to autodoc-style documentation, + you may want to turn the :confval:`autoapi_generate_api_docs` + option off so that automatic API documentation is no longer generated. To use these directives you will need to enable the autodoc extension in your Sphinx project's ``conf.py``: diff --git a/docs/reference/templates.rst b/docs/reference/templates.rst new file mode 100644 index 0000000..d398e7e --- /dev/null +++ b/docs/reference/templates.rst @@ -0,0 +1,98 @@ +Templates +========= + +A lot of the power from AutoAPI comes from templates. +We are basically building a mapping from code to docs, +and templates let you highly customise the display of said docs. + +Structure +--------- + +Every type of data structure has its own template. +It uses the form :samp:`{language}/{type}.rst` to find the template to render. +The full search path is: + + * :samp:`{language}/{type}.rst` + +So for a .NET Class, this would resolve to: + + * :samp:`dotnet/class.rst` + +We provide :samp:`base/base.rst` as an incredibly basic output of every object:: + + .. {language}:{type}:: {name} + +Context +------- + +Every template is given a set context that can be accessed in the templates. +This contains: + +* ``obj``: A Python object derived from :class:`PythonMapperBase`. + +This object has a number of standard attributes you can reliably access per language. + +.. warning:: + + These classes should not be constructed manually. + They can be reliably accessed through templates only. + +Python +~~~~~~ + +.. autoapiclass:: autoapi.mappers.python.objects.PythonPythonMapper + :members: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonFunction + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonMethod + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonData + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonAttribute + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.TopLevelPythonPythonMapper + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonModule + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonPackage + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonClass + :members: + :show-inheritance: + +.. autoapiclass:: autoapi.mappers.python.objects.PythonException + :members: + :show-inheritance: + +Go +~~~ + +.. autoapiclass:: autoapi.mappers.go.GoPythonMapper + :members: + +Javascript +~~~~~~~~~~ + +.. autoapiclass:: autoapi.mappers.javascript.JavaScriptPythonMapper + :members: + +.NET +~~~~ + +.. autoapiclass:: autoapi.mappers.dotnet.DotNetPythonMapper + :members: diff --git a/docs/templates.rst b/docs/templates.rst deleted file mode 100644 index 980e6ec..0000000 --- a/docs/templates.rst +++ /dev/null @@ -1,41 +0,0 @@ -Templates ---------- - -A lot of the power from AutoAPI comes from templates. -We are basically building a mapping from Code to Docs, -and templates let you highly customize the display of said docs. - -Structure -~~~~~~~~~ - -Every type of data structure gets its own template. -It uses the form :samp:`{language}/{type}.rst` to find the template to render. -The full search path is: - - * :samp:`{language}/{type}.rst` - * :samp:`{language}/unknown.rst` - * :samp:`base/unknown.rst` - -So for a .Net Class, this would resolve to: - - * :samp:`{dotnet}/{class}.rst` - * :samp:`{dotnet}/unknown.rst` - * :samp:`base/unknown.rst` - -We provide :samp:`base/member.rst` as an incredibly basic output of every object:: - - .. {language}:{type}:: {name} - -Context -~~~~~~~ - -Every template will be given a set context. It will contain: - - * `obj`: A Python object derived from - -This object has a number of standard attributes you can reliably access: - - * **id** - A unique identifier - * **type** - The objects type, lowercase - * **name** - A user displayable name - * **item_map** - A dict with keys containing the types this object has as children, and values of those objects. diff --git a/docs/tutorials.rst b/docs/tutorials.rst new file mode 100644 index 0000000..1429476 --- /dev/null +++ b/docs/tutorials.rst @@ -0,0 +1,232 @@ +Tutorials +========= + +Setting up Automatic API Documentation Generation +------------------------------------------------- + +This tutorial will assume that you already have a basic Sphinx project set up. +If you are not sure how to do this, +you can following the :doc:`sphinx:usage/quickstart` guide in the Sphinx documentation. + +The recommended way of installing AutoAPI is through a `virtualenv `_. +Once you have a virtualenv set up, you can install AutoAPI with the command:: + + pip install sphinx-autoapi + +Depending on which language you are trying to document, +each language has a different set of steps for finishing the setup of AutoAPI: + +.. contents:: + :local: + :backlinks: none + + +Python +^^^^^^ + +To enable the extension, +we need to add it to the list of extensions in Sphinx's ``conf.py`` file:: + + extensions = ['autoapi.extension'] + +For Python, there is only one required configuration option that we need to set. +:confval:`autoapi_dirs` tells AutoAPI which directories contain +the source code to document. +These can either be absolute, or relative to where you run Sphinx. +For example, say we have a package and we have used ``sphinx-quickstart`` +to create a Sphinx project in a ``docs/`` folder. +The directory structure might look like this: + +.. code-block:: + + mypackage/ + ├── docs + │   ├── _build + │   ├── conf.py + │   ├── index.rst + │   ├── make.bat + │   ├── Makefile + │   ├── _static + │   └── _templates + ├── mypackage + │   ├── _client.py + │   ├── __init__.py + │   └── _server.py + └── README.md + +``sphinx-quickstart`` sets up the ``sphinx-build`` to run from +inside the ``docs/`` directory, and the source code is one level up. +So the value of our :confval:`autoapi_dirs` option would be:: + + autoapi_dirs = ['../mypackage'] + +If you are documenting many packages, +you can point AutoAPI to the directory that contains those packages. +For example if our source code was inside a ``src/`` directory: + +.. code-block:: + + mypackage/ + ├── docs + │   ├── _build + │   ├── conf.py + │   ├── index.rst + │   ├── make.bat + │   ├── Makefile + │   ├── _static + │   └── _templates + ├── README.md + └── src + └── mypackage + ├── _client.py + ├── __init__.py + └── _server.py + +We can configure :confval:`autoapi_dirs` to be:: + + autoapi_dirs = ['../src'] + +Now that everything is configured, +AutoAPI will generate documentation when you run Sphinx! + +.. code-block:: + + cd docs/ + sphinx-build -b html . _build + + +Go +^^^ + +Support for Go requires you to have the go environment installed +(https://golang.org/dl/), as well as our godocjson tool:: + + go get github.com/rtfd/godocjson + +and the Go domain extension for Sphinx:: + + pip install sphinxcontrib-golangdomain + +To enable the AutoAPI extension, +we need to add it to the list of extensions in Sphinx's ``conf.py`` file +with the Go domain extension:: + + extensions = [ + 'sphinxcontrib_golangdomain', + 'autoapi.extension', + ] + +For Go, there are two required configuration options that we need to set. +:confval:`autoapi_type` tells AutoAPI what type of language we are documenting. +For Go, this is:: + + autoapi_type = 'go' + +The second configuration option is :confval:`autoapi_dirs`, +which tells AutoAPI which directories contain the source code to document. +These can either be absolute, or relative to where you run Sphinx. +So if your documentation was inside a ``docs/`` directory +and your source code is in an ``example`` directory one level up, +you would configure :confval:`autoapi_dirs` to be:: + + autoapi_dirs = ['../example'] + +Now that everything is configured, +AutoAPI will generate documentation when you run Sphinx! + +.. code-block:: + + cd docs/ + sphinx-build -b html . _build + + +Javscript +^^^^^^^^^ + +Support for Javascript requires you to have jsdoc (http://usejsdoc.org/) installed:: + + npm install jsdoc -g + +To enable the AutoAPI extension, +we need to add it to the list of extensions in Sphinx's ``conf.py`` file:: + + extensions = ['autoapi.extension'] + +For Javascript, there are two required configuration options that we need to set. +:confval:`autoapi_type` tells AutoAPI what type of language we are documenting. +For Javascript, this is:: + + autoapi_type = 'javascript' + +The second configuration option is :confval:`autoapi_dirs`, +which tells AutoAPI which directories contain the source code to document. +These can either be absolute, or relative to where you run Sphinx. +So if your documentation was inside a ``docs/`` directory +and your source code is in an ``example`` directory one level up, +you would configure :confval:`autoapi_dirs` to be:: + + autoapi_dirs = ['../example'] + +Now that everything is configured, +AutoAPI will generate documentation when you run Sphinx! + +.. code-block:: + + cd docs/ + sphinx-build -b html . _build + + +.NET +^^^^ + +Support for .NET requires you to have the docfx (https://dotnet.github.io/docfx/) tool installed, +as well as the .NET domain extension for Sphinx:: + + pip install sphinxcontrib-dotnetdomain + +Firstly, we need to configure docfx to output to a directory known to AutoAPI. +By default, ``docfx`` will output metadata files into the ``_api`` path. +You can configure which path to output files into by setting the path in your +`docfx configuration file `_ +in your project repository. +For example, if your ``conf.py`` file is located inside a ``docs/`` directory: + +.. code:: json + + { + "metadata": [{ + "dest": "docs/_api" + }] + } + +To enable the AutoAPI extension, +we need to add it to the list of extensions in Sphinx's ``conf.py`` file +with the .NET domain extension:: + + extensions = [ + 'sphinxcontrib.dotnetdomain', + 'autoapi.extension', + ] + +For .NET, there are two required configuration options that we need to set. +:confval:`autoapi_type` tells AutoAPI what type of language we are documenting. +For .NET, this is:: + + autoapi_type = 'dotnet' + +The second configuration option is :confval:`autoapi_dirs`, +which tells AutoAPI which directories contain the source code to document. +These can either be absolute, or relative to where you run Sphinx. +So if your documentation was inside a ``docs/`` directory +and your source code is in an ``example`` directory one level up, +you would configure :confval:`autoapi_dirs` to be:: + + autoapi_dirs = ['../example'] + +Now that everything is configured, +AutoAPI will generate documentation when you run Sphinx! + +.. code-block:: + + cd docs/ + sphinx-build -b html . _build diff --git a/setup.py b/setup.py index 06b0501..f2e636b 100644 --- a/setup.py +++ b/setup.py @@ -10,7 +10,7 @@ setup( author_email='eric@ericholscher.com', url='http://github.com/rtfd/sphinx-autoapi', license='BSD', - description='Sphinx auto API documentation generator', + description='Sphinx API documentation generator', packages=find_packages('.'), long_description=codecs.open("README.rst", "r", "utf-8").read(), include_package_data=True, @@ -23,4 +23,21 @@ setup( 'sphinxcontrib-dotnetdomain', 'unidecode', ], + python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*', + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Plugins', + 'Framework :: Sphinx :: Extension', + 'Intended Audience :: Developers', + 'License :: OSI Approved :: MIT License', + 'Natural Language :: English', + 'Programming Language :: Python', + 'Programming Language :: Python :: 2', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3.4', + 'Programming Language :: Python :: 3.5', + 'Programming Language :: Python :: 3.6', + 'Programming Language :: Python :: 3.7', + ], ) diff --git a/tests/goexample/Makefile b/tests/goexample/Makefile deleted file mode 100644 index b56e8d3..0000000 --- a/tests/goexample/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -v -v -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/tests/jsexample/Makefile b/tests/jsexample/Makefile deleted file mode 100644 index b56e8d3..0000000 --- a/tests/jsexample/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -v -v -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/tests/python/pyexample/Makefile b/tests/python/pyexample/Makefile deleted file mode 100644 index b56e8d3..0000000 --- a/tests/python/pyexample/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -v -v -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/tests/templateexample/Makefile b/tests/templateexample/Makefile deleted file mode 100644 index b56e8d3..0000000 --- a/tests/templateexample/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -v -v -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/tests/toctreeexample/Makefile b/tests/toctreeexample/Makefile deleted file mode 100644 index b56e8d3..0000000 --- a/tests/toctreeexample/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -v -v -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxAutoAPI.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxAutoAPI.qhc" - -applehelp: - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxAutoAPI" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/tox.ini b/tox.ini index e845864..0753f12 100644 --- a/tox.ini +++ b/tox.ini @@ -44,8 +44,8 @@ commands = [testenv:docs] deps = - Sphinx>=1.8,<=1.9 + Sphinx>=2.0,<=2.1 sphinx_rtd_theme changedir = {toxinidir}/docs commands = - sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html + sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html