Related P302

This document is supposed to be just the bare minimum to have a working
local swh-environment. Users shouldn't need any information about
advanced PostgreSQL setup and should just use the easiest auth method
(peer authentication).

Antoine Pietri authored 6 years ago and Stefano Zacchiroli committed 6 years ago

Reviewers: zack

Subscribers: zack

Differential Revision: https://forge.softwareheritage.org/D430

As a consequence of rDWAPPSb06167c8ab05

there is no need of separately creating the webpack

Closes T1193

we have a better bin/update now

Related T1193

Related T1193

the default highlighting directive put between page anchor got in the way of
extracting page title, making the page non-referencable

in doing so, switch to the current, non-obsolete format for specifying
intersphinx mappings

Related T1193

still to do: dependency installation, web app

Related T1193

Related T1193

Rather than one big page for each top-level module, containing the apidoc of
all submodules.

This commit slighly modifies Makefiles in order to be able to build
the documentation on Debian stretch (using sphinx 1.4.9) but also
with the latest sphinx version to date (1.7.5).

Changes notably includes:

  - remove the --implicit-namespaces option for sphinx-apidoc as:

     * it is not needed
     * it is not supported on sphinx 1.4.9
     * output is not correct with sphinx 1.7.5

  - use sphinx -b option instead of -M for building html doc
    as an exception is raised otherwise when using sphinx 1.4.9

Related T1067

  - use the Alegreya font as in the other swh websites

  - add top navigation bar to efficiently jump between swh websites

Related T1065

This commit adds a postprocessing step on the generated html documentation for swh.
Its purpose is to modify the indices and search scope in each swh subproject doc.

Prior to that, when browsing a subproject doc, indices and search were scoped
to all swh projects. This was not really convenient for the reader who only
wanted to focus on a specific subproject. Now indices and search are only scoped
to each swh subproject content.

Nevertheless, global indices and search are still available from the
root documentation index.

This makes doc building more expensive (because it effectively get
built *twice*), but has the advantage of calling make in all modules, so that
auxiliary pieces of documentation (e.g., DB schemes) are guaranteed to be built
as well.

It also makes sure that everyone who wants to build the global doc has all the
needed dependencies, avoiding inconsistent builds by different people that step
on each other toes.

also, use anchors to link to modules rather than relying on generated HTML file
names

hack to set the adequate settings module based on which project doc is built),
activate extlinks extension for swh-web and add links to swh projects dedicated doc
on the index page but also a link to the swh urls index