Documentation overhaul
Ashley Whetter
5 years ago
parent
dd58809d89
commit
7230330686
@ -0,0 +1,152 @@
|
||||
Changelog
|
||||
=========
|
||||
|
||||
Versions follow `Semantic Versioning <https://semver.org/>`_ (``<major>.<minor>.<patch>``).
|
||||
|
||||
vTBC
|
||||
----
|
||||
|
||||
Features
|
||||
~~~~~~~~
|
||||
|
||||
* `#100 <https://github.com/rtfd/sphinx-autoapi/issues/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 <https://github.com/rtfd/sphinx-autoapi/issues/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 <https://github.com/rtfd/sphinx-autoapi/issues/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 <https://github.com/rtfd/sphinx-autoapi/issues/152>`: Removed the ``autoapi_add_api_root_toctree`` option.
|
||||
|
||||
This has been replaced with the ``autoapi_add_toctree_entry`` option.
|
||||
|
||||
* `#25 <https://github.com/rtfd/sphinx-autoapi/issues/25>`: Removed distutils support.
|
||||
* Removed redundant ``package_dir`` and ``package_data`` options.
|
||||
|
||||
Features
|
||||
~~~~~~~~
|
||||
|
||||
* (Python) Added viewcode support for imported members.
|
||||
* `#146 <https://github.com/rtfd/sphinx-autoapi/issues/146>`: (Python) No longer documents ``__init__()`` attributes without a docstring.
|
||||
* `#153 <https://github.com/rtfd/sphinx-autoapi/issues/153>`: (Python) Can document a public python API.
|
||||
* `#111 <https://github.com/rtfd/sphinx-autoapi/issues/111>`: (Python) Can opt to write manual documentation through new autodoc-style directives.
|
||||
* `#152 <https://github.com/rtfd/sphinx-autoapi/issues/152>`: Made it easier to remove default index page.
|
||||
|
||||
Also removed autoapi_add_api_root_toctree config option
|
||||
|
||||
* `#150 <https://github.com/rtfd/sphinx-autoapi/issues/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 <https://github.com/rtfd/sphinx-autoapi/issues/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 <https://github.com/rtfd/sphinx-autoapi/issues/148>`: (Python) Fixed astroid 2.0 compatibility.
|
||||
* (Python) Fixed filtered classes and attributes getting displayed.
|
||||
* (Python) Fixed incorrect display of long lists.
|
||||
* `#125 <https://github.com/rtfd/sphinx-autoapi/issues/125>`: (Javacript) Fixed running incorrect jsdoc command on Windows.
|
||||
* `#125 <https://github.com/rtfd/sphinx-autoapi/issues/125>`: (Python) Support specifying package directories in ``autoapi_dirs``.
|
||||
|
||||
Trivial/Internal Changes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Added Sphinx 1.7 and 1.8.0b1 testing.
|
||||
* `#120 <https://github.com/rtfd/sphinx-autoapi/issues/120>`: Updated documentation to remove outdated references.
|
||||
* Removed old testing dependencies.
|
||||
* `#143 <https://github.com/rtfd/sphinx-autoapi/issues/143>`: Removed unnecessary wheel dependency.
|
||||
@ -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
|
||||
@ -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 <target>' where <target> 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
|
||||
@ -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
|
||||
@ -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 <customise-templates>`.
|
||||
|
||||
|
||||
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.
|
||||
@ -1 +1,11 @@
|
||||
.. include:: ../README.rst
|
||||
Sphinx AutoAPI
|
||||
==============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
tutorials
|
||||
how_to
|
||||
reference/*
|
||||
maintenance/*
|
||||
|
||||
@ -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.
|
||||
@ -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/*
|
||||
@ -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 <https://github.com/rtfd/sphinx-autoapi/tree/master/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.
|
||||
@ -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``:
|
||||
@ -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:
|
||||
@ -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.
|
||||
@ -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 <https://virtualenv.pypa.io/>`_.
|
||||
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 <https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#3-docfx-json-format>`_
|
||||
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
|
||||
@ -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 <target>' where <target> 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
|
||||
@ -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 <target>' where <target> 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
|
||||
@ -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 <target>' where <target> 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
|
||||
@ -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 <target>' where <target> 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
|
||||
@ -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 <target>' where <target> 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
|
||||
Loading…
Reference in New Issue