diff --git a/docs/Makefile b/docs/Makefile index 5729d9e..815604a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,56 +1,60 @@ SPHINXOPTS = SPHINXBUILD = python3 -c 'import sphinx, sys; sys.exit(sphinx.main(sys.argv))' SOURCEDIR = . BUILDDIR = _build HTMLDIR = $(BUILDDIR)/html INSTALL_HOST = pergamon.internal.softwareheritage.org INSTALL_DIR = /srv/softwareheritage/docs/webroot/devel INSTALL_GROUP = swhdev INSTALL_PERMS = g+rwX +html: fix-indices-stamp sphinx/html + +fix-indices-stamp: sphinx/html + bin/copy-and-fix-subprojects-indices + touch $@ -html: sphinx/html sphinx/html: links-stamp apidoc-stamp images-stamp rec-build-stamp links-stamp: bin/ln-sphinx-subprojects touch $@ apidoc-stamp: $(MAKE) -C ../../ docs-apidoc touch $@ images-stamp: $(MAKE) -C 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 touch $@ clean: sphinx/clean bin/ln-sphinx-subprojects --remove $(MAKE) -C images clean rm -f *-stamp distclean: clean make -C ../../ docs-clean help: sphinx/help sphinx/%: @$(SPHINXBUILD) -M $* "$(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 diff --git a/docs/bin/copy-and-fix-subprojects-indices b/docs/bin/copy-and-fix-subprojects-indices new file mode 100755 index 0000000..001a429 --- /dev/null +++ b/docs/bin/copy-and-fix-subprojects-indices @@ -0,0 +1,52 @@ +#!/bin/bash + +# The global generated swh documentation lacks local scoping when browsing subprojects +# documentation. For instance, when browsing the swh-model doc, indices and search are +# scoped to all swh modules which is not really convenient as the reader only wants to +# focus on swh-model. + +# This postprocess script is used to copy each swh module indices generated by Sphinx +# into the global swh html documentation tree. +# The script also takes care of fixing the indices references in the generated html files, +# thus pointing to subprojects indices when browsing their dedicated documentation. + +# Copy subprojects index files from their standalone documentation to the global swh +# documentation tree anf fix paths to assets once it is done +declare -a index_files=("genindex.html" "py-modindex.html" "search.html" "searchindex.js" "http-routingtable.html") +for pymodule in $(cd ../../ && bin/ls-py-modules) ; do + if [ "$pymodule" = 'swh-docs' ] ; then + continue + fi + orig_index_path="$pymodule/_build/html" + cp_index_path="_build/html/$pymodule" + for index_file in "${index_files[@]}" + do + if [ -e "$orig_index_path/$index_file" ] ; then + cp "$orig_index_path/$index_file" "$cp_index_path/$index_file" + sed -i 's/_static/\.\.\/_static/g' "$cp_index_path/$index_file" + fi + done +done + +# Fix some file paths in subprojects documentation for a better navigation. +# When navigating in a subproject doc, we want to get back to its index page +# when clicking on the top left swh logo. +# The only exception is for a subproject doc index page: when clicking on the +# swh logo, we get back to the root doc index. +declare -a file_to_fix_path_in_subproject=("index\.html" "search\.html" "genindex\.html") +for file in "${file_to_fix_path_in_subproject[@]}" +do + find . -mindepth 4 -maxdepth 4 -name *.html ! -name index.html | xargs sed -i "s/\"\.\.\/$file\"/\"$file\"/g" + find . -mindepth 5 -maxdepth 5 -name *.html ! -name index.html | xargs sed -i "s/\"\.\.\/\.\.\/$file\"/\"\.\.\/$file\"/g" +done + +# Fix paths to subprojects indices. When navigating in a subproject doc +# we want to use indices only scoped to that subproject. +# Global indices and search are still available from the doc root index page +declare -a file_to_fix_path_in_subproject_index=("genindex\.html" "py-modindex\.html" "search\.html") +for file in "${file_to_fix_path_in_subproject_index[@]}" +do + find . -name index.html | xargs sed -i "s/\"\.\.\/$file\"/\"$file\"/g" +done +# Ensure the root toc link points to each subproject doc index page +find . -name index.html | xargs sed -i 's/"\.\.\/index\.html">Table Of Contents/"index\.html">Table Of Contents/g' diff --git a/docs/index.rst b/docs/index.rst index d2b853f..1fcaf6e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,108 +1,108 @@ .. _swh-docs: Software Heritage - Development Documentation ============================================= .. toctree:: :maxdepth: 2 :caption: Contents: Components ---------- Here is brief overview of the most relevant software components in the Software Heritage stack. Each component name is linked to the development documentation of the corresponding Python module. :ref:`swh.archiver ` orchestrator in charge of guaranteeing that object storage content is pristine and available in a sufficient amount of copies :ref:`swh.core ` low-level utilities and helpers used by almost all other modules in the stack :ref:`swh.deposit ` push-based deposit of software artifacts to the archive swh.docs developer documentation (used to generate this doc you are reading) :ref:`swh.indexer ` tools and workers used to crawl the content of the archive and extract derived information from any artifact stored in it :ref:`swh.journal ` persistent logger of changes to the archive, with publish-subscribe support :ref:`swh.lister ` collection of listers for all sorts of source code hosting and distribution places (forges, distributions, package managers, etc.) :ref:`swh.loader-core ` low-level loading utilities and helpers used by all other loaders :ref:`swh.loader-debian ` loader for `Debian `_ source packages :ref:`swh.loader-dir ` loader for source directories (e.g., expanded tarballs) :ref:`swh.loader-git ` loader for `Git `_ repositories :ref:`swh.loader-mercurial ` loader for `Mercurial `_ repositories :ref:`swh.loader-svn ` loader for `Subversion `_ repositories :ref:`swh.loader-tar ` loader for source tarballs (including Tar, ZIP and other archive formats) :ref:`swh.model ` implementation of the :ref:`data-model` to archive source code artifacts :ref:`swh.objstorage ` content-addressable object storage :ref:`swh.scheduler ` task manager for asynchronous/delayed tasks, used for recurrent (e.g., listing a forge, loading new stuff from a Git repository) and one-off activities (e.g., loading a specific version of a source package) :ref:`swh.storage ` abstraction layer over the archive, allowing to access all stored source code artifacts as well as their metadata :ref:`swh.vault ` implementation of the vault service, allowing to retrieve parts of the archive as self-contained bundles (e.g., individual releases, entire repository snapshots, etc.) :ref:`swh.web ` Web application(s) to browse the archive, for both interactive (HTML UI) and mechanized (REST API) use Dependencies -~~~~~~~~~~~~ +------------ The dependency relationships among the various modules are depicted below. .. _py-deps-swh: .. figure:: images/py-deps-swh.svg :width: 1024px :align: center Dependencies among top-level Python modules (click to zoom). Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * `URLs index `_ * :ref:`search`