Display any generated static API documentation in a sidebar
Project description
Sphinx API Sidebar
A Sphinx extension for displaying any generated static API documentation in a sidebar.
Overview
This Sphinx extension allows you to automatically include and display static API documentation (e.g., JavaDoc, Python's Sphinx-generated HTML) in the sidebar of your Sphinx documentation. It updates the html_context
with the API documentation paths, which can then be used in the sidebar.
Installation
To install the sphinx-api-sidebar
extension, you can use pip:
pip install sphinx-api-sidebar
Usage
- To enable the sphinx-api-sidebar extension in your Sphinx documentation project, add it to the extensions list in your conf.py file:
extensions = [
'sphinx_api_sidebar',
# Other extensions...
]
- To use a custom command to generate your API documentation or specify different directories, you can set the api_docs_generator configuration value in your conf.py file:
api_docs_generator = [
'<your_custom_build_command>',
[
{
'name': '<generated_api_doc_name>',
'path': '<path_to_generated_api_doc>'
},
# Add more dictionaries for each additional API doc
]
]
Replace <your_custom_build_command>, <generated_api_doc_name>, and <path_to_generated_api_doc> with the appropriate values for your project.
- To make the different api documentation show up in the sidebar, you will need to copy the
api_docs_sidebar.html
template file from thesphinx_api_sidebar/templates
folder of the installed package to your Sphinx project's _templates folder. Alternatively, you can create a new file in your project's _templates folder with the following content:
{% if api_docs %}
<h3>{{ _('API Documentation') }}</h3>
<ul style="list-style-type: none;">
{%- for item in api_docs %}
<li style="margin-bottom: 10px;"><a href="{{ pathto('_static/api-docs/{}'.format(item), 1) }}">{{ item }}</a></li>
{%- endfor %}
</ul>
{% endif %}
- Update your
conf.py
file to include theapi_docs_sidebar.html
template in the html_sidebars configuration:
html_sidebars = {
'**': [
# ... other sidebars ...
'api_docs_sidebar.html',
]
}
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_api_sidebar-0.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a3cdb3e1849e7504b203469927748127f9a141e3ed9f76f51ccf2c6af6c60fe8 |
|
MD5 | a8f22ec680bed1c90c278777fe6cfb1a |
|
BLAKE2b-256 | d015f7f5bae232fbded67f0141902454c50d6145d9805fe7862c163c963d81b2 |