diff options
author | Antoine Beaupré <anarcat@koumbit.org> | 2015-09-30 18:35:54 -0400 |
---|---|---|
committer | Antoine Beaupré <anarcat@koumbit.org> | 2015-09-30 18:35:57 -0400 |
commit | a2cf0025c23e938029e023116167ec7d74583da1 (patch) | |
tree | ab6e620f620573a6cdbea60888383dfe0a0adb8e /docs | |
parent | 3b1fae6b3449b204bd1609096d0e4fa8f1ece976 (diff) |
add automatically generated API
this is a crude hack for now, and could use a better table of contents
but at least we have some way of linking and showing the different
internal functions
the next phase here is obviously to document that API through the
addition of docstrings. a static api.rst could also be easier to read,
but maybe that could go through some docstrings as well, to be tested
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Makefile | 17 | ||||
-rw-r--r-- | docs/conf.py | 2 | ||||
-rw-r--r-- | docs/index.rst | 1 |
3 files changed, 18 insertions, 2 deletions
diff --git a/docs/Makefile b/docs/Makefile index 1f3f7d76c..133080cdb 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -36,7 +36,7 @@ help: clean: -rm -rf $(BUILDDIR)/* -html: usage +html: usage api.rst $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @@ -153,3 +153,18 @@ usage/%.rst.inc: ../borg/archiver.py @borg help $* --usage-only | sed -e 's/^/ /' >> $@ @printf "\nDescription\n~~~~~~~~~~~\n" >> $@ @borg help $* --epilog-only >> $@ + +api.rst: Makefile + @echo "auto-generating API documentation" + @echo "Borg Backup API documentation" > $@ + @echo "=============================" >> $@ + @echo "" >> $@ + @for mod in ../borg/*.pyx ../borg/*.py; do \ + if echo "$$mod" | grep -q "/_"; then \ + continue ; \ + fi ; \ + printf ".. automodule:: "; \ + echo "$$mod" | sed "s!\.\./!!;s/\.pyx\?//;s!/!.!"; \ + echo " :members:"; \ + echo " :undoc-members:"; \ + done >> $@ diff --git a/docs/conf.py b/docs/conf.py index 772d88498..eba5c841e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -218,7 +218,7 @@ latex_documents = [ # ['see "AUTHORS" file'], 1) #] -extensions = ['sphinx.ext.extlinks'] +extensions = ['sphinx.ext.extlinks', 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] extlinks = { 'issue': ('https://github.com/borgbackup/borg/issues/%s', '#'), diff --git a/docs/index.rst b/docs/index.rst index a871ef353..6a42dce0f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,3 +16,4 @@ Borg Documentation changes internals development + api |