You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
87 lines
2.8 KiB
ReStructuredText
87 lines
2.8 KiB
ReStructuredText
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.
|