Documentation overhaul
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
|
Copyright (c) 2015 Read the Docs, Inc
|
||||||
|
|
||||||
Permission is hereby granted, free of charge, to any person
|
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 document talks about the design of a .NET Sphinx integration.
|
||||||
This will include a mechanism for generating Javadoc style API references automatically.
|
This will include a mechanism for generating Javadoc style API references automatically.
|
||||||
We will describe decisions that lead to specific implementation details.
|
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
|
Autodoc-Style Directives
|
||||||
------------------------
|
========================
|
||||||
|
|
||||||
You can opt to write API documentation yourself using autodoc style directives.
|
You can opt to write API documentation yourself using autodoc style directives.
|
||||||
These directives work similarly to autodoc,
|
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
|
To use these directives you will need to enable the autodoc extension
|
||||||
in your Sphinx project's ``conf.py``:
|
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