diff --git a/docs/Makefile b/docs/Makefile index 1d70610..62bea9d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,72 +1,79 @@ SPHINXOPTS ?= SPHINXBUILD = sphinx-build SOURCEDIR = . BUILDDIR = _build HTMLDIR = $(BUILDDIR)/html SWHPKGDIR ?= sources/swh/ INSTALL_HOST = pergamon.internal.softwareheritage.org INSTALL_DIR = /srv/softwareheritage/docs/webroot/devel INSTALL_GROUP = swhdev INSTALL_PERMS = g+rwX SPHINXAPIDOC = sphinx-apidoc APIDOC_DIR = apidoc APIDOC_OPTS = --ext-viewcode --separate APIDOC_EXCLUDES = */tests */tests/* */*/tests/* */*/*/tests/* APIDOC_EXCLUDES += */migrations */migrations/* */*/migrations/* */*/*/migrations/* APIDOC_EXCLUDES += */wsgi.py */*/wsgi.py */*/*/wsgi.py */*/*/wsgi.py APIDOC_EXCLUDES += deposit/settings/* web/settings/* dataset/* APIDOC_SWH_EXCLUDES = $(patsubst %,$(SWHPKGDIR)/%,$(APIDOC_EXCLUDES)) html: sphinx/html sphinx/html: links-stamp apidoc-stamp images-stamp rec-build-stamp links-stamp: bin/ln-sphinx-subprojects touch $@ apidoc: apidoc-stamp apidoc-stamp: links-stamp - $(SPHINXAPIDOC) --implicit-namespaces $(APIDOC_OPTS) -o $(APIDOC_DIR) $(SWHPKGDIR) $(APIDOC_SWH_EXCLUDES) + $(SPHINXAPIDOC) \ + --implicit-namespaces \ + --templatedir=../swh/docs/templates/ \ + --maxdepth=3 \ + $(APIDOC_OPTS) \ + -o $(APIDOC_DIR) \ + $(SWHPKGDIR) \ + $(APIDOC_SWH_EXCLUDES) touch $@ images-stamp: $(MAKE) -C images $(MAKE) -C swh-deposit/images touch $@ # Build documentation recursively in all packages, to make sure that auxiliary, # non-sphinx managed documentation artifacts (e.g., schema diagrams) are also # built. rec-build-stamp: $(wildcard ../../swh-*/docs/*.rst) $(MAKE) -C ../../ docs-assets touch $@ clean: sphinx/clean bin/ln-sphinx-subprojects --remove $(MAKE) -C images clean rm -f *-stamp rm -f $(APIDOC_DIR)/* distclean: clean make -C ../../ docs-clean help: sphinx/help sphinx/clean: $(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) sphinx/%: $(SPHINXBUILD) -b $* "$(SOURCEDIR)" "$(BUILDDIR)/$*" $(SPHINXOPTS) install: html test -d $(HTMLDIR) rsync -rlvuz --delete $(BUILDDIR)/html/ $(INSTALL_HOST):$(INSTALL_DIR)/ ssh $(INSTALL_HOST) \ "find $(INSTALL_DIR) -not -group $(INSTALL_GROUP) -exec chgrp -v $(INSTALL_GROUP) {} + ; \ find $(INSTALL_DIR) -not -perm -ug=rw,o=r -exec chmod -v ug+rw,o+r {} + ; \ find $(INSTALL_DIR) -type d -not -perm -g=xs,ou=x -exec chmod -v g+xs,ou+x {} +" .PHONY: help html clean distclean install images-stamp diff --git a/swh/docs/templates/package.rst_t b/swh/docs/templates/package.rst_t new file mode 100644 index 0000000..13b80ef --- /dev/null +++ b/swh/docs/templates/package.rst_t @@ -0,0 +1,54 @@ +{# copy-pasted from sphinx/templates/apidoc/package.rst_t, but makes + "Subpackages", "Submodules", and "Module Contents" simple text instead + of headings #} +{%- macro automodule(modname, options) -%} +.. automodule:: {{ modname }} +{%- for option in options %} + :{{ option }}: +{%- endfor %} +{%- endmacro %} + +{%- macro toctree(docnames) -%} +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} +{%- endmacro %} + +{%- if is_namespace %} +{{- [pkgname, "namespace"] | join(" ") | e | heading }} +{% else %} +{{- [pkgname, "package"] | join(" ") | e | heading }} +{% endif %} + +{%- if modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} + +{%- if subpackages %} +Subpackages: + +{{ toctree(subpackages) }} +{% endif %} + +{%- if submodules %} +Submodules: + +{% if separatemodules %} +{{ toctree(submodules) }} +{% else %} +{%- for submodule in submodules %} +{% if show_headings %} +{{- [submodule, "module"] | join(" ") | e | heading(2) }} +{% endif %} +{{ automodule(submodule, automodule_options) }} +{% endfor %} +{%- endif %} +{%- endif %} + +{%- if not modulefirst and not is_namespace %} +Module contents: + +{{ automodule(pkgname, automodule_options) }} +{% endif %}