Page MenuHomeSoftware Heritage
Files F8391136

No OneTemporary
Actions

View Options

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 %}

File Metadata

Mime Type
text/x-diff
Expires
Jun 4 2025, 6:39 PM (14 w, 4 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3345846

Event Timeline

About · Developer information · Legal