mirror of
https://github.com/certbot/certbot.git
synced 2026-01-29 10:02:08 +03:00
ceea41c1e2
It looks like we're currently documenting functions that are marked private (prefixed with an underscore) such as https://certbot.eff.org/docs/api/certbot.crypto_util.html#certbot.crypto_util._load_cert_or_req. I do not think we should do this because the functionality is private, should not be used, and including it in our docs just adds visual noise. This PR stops us from documenting private code and fixes up `tools/sphinx-quickstart.sh` so we don't document it in future modules. * Do not document private code. * Don't document private members in the future.
33 lines
2.1 KiB
Bash
Executable File
33 lines
2.1 KiB
Bash
Executable File
#!/bin/bash
|
|
|
|
if [ $# -ne 1 ]; then
|
|
echo "Usage: $(basename $0) project-name"
|
|
exit 1
|
|
fi
|
|
|
|
PROJECT=$1
|
|
|
|
yes "n" | sphinx-quickstart --dot _ --project $PROJECT --author "Certbot Project" -v 0 --release 0 --language en --suffix .rst --master index --ext-autodoc --ext-intersphinx --ext-todo --ext-coverage --ext-viewcode --makefile --batchfile $PROJECT/docs
|
|
|
|
cd $PROJECT/docs
|
|
sed -i -e "s|\# import os|import os|" conf.py
|
|
sed -i -e "s|\# needs_sphinx = '1.0'|needs_sphinx = '1.0'|" conf.py
|
|
sed -i -e "s|intersphinx_mapping = {'https://docs.python.org/': None}|intersphinx_mapping = {\n 'python': ('https://docs.python.org/', None),\n 'acme': ('https://acme-python.readthedocs.org/en/latest/', None),\n 'certbot': ('https://certbot.eff.org/docs/', None),\n}|" conf.py
|
|
sed -i -e "s|html_theme = 'alabaster'|\n# http://docs.readthedocs.org/en/latest/theme.html#how-do-i-use-this-locally-and-on-read-the-docs\n# on_rtd is whether we are on readthedocs.org\non_rtd = os.environ.get('READTHEDOCS', None) == 'True'\nif not on_rtd: # only import and set the theme if we're building docs locally\n import sphinx_rtd_theme\n html_theme = 'sphinx_rtd_theme'\n html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]\n# otherwise, readthedocs.org uses their theme by default, so no need to specify it|" conf.py
|
|
sed -i -e "s|# Add any paths that contain templates here, relative to this directory.|autodoc_member_order = 'bysource'\nautodoc_default_flags = ['show-inheritance']\n\n# Add any paths that contain templates here, relative to this directory.|" conf.py
|
|
sed -i -e "s|# The name of the Pygments (syntax highlighting) style to use.|default_role = 'py:obj'\n\n# The name of the Pygments (syntax highlighting) style to use.|" conf.py
|
|
echo "/_build/" >> .gitignore
|
|
echo "=================
|
|
API Documentation
|
|
=================
|
|
|
|
.. toctree::
|
|
:glob:
|
|
|
|
api/**" > api.rst
|
|
sed -i -e "s| :caption: Contents:| :caption: Contents:\n\n.. automodule:: ${PROJECT//-/_}\n :members:\n\n.. toctree::\n :maxdepth: 1\n\n api|" index.rst
|
|
|
|
echo "Suggested next steps:
|
|
* Add API docs to: $PROJECT/docs/api/
|
|
* Run: git add $PROJECT/docs"
|