add a documentation landing page

docs/_templates/layout.html

@@ -16,8 +16,43 @@
 <!-- End Matomo Code -->
 {% endblock %}
 
+{# copied from sphinx_rtd_theme/layout.html, with the logo link pointing to General (landing page) #}
+{%- block sidebartitle %}
+{%- if logo and theme_logo_only %}
+  <a href="/general/">
+{%- else %}
+  <a href="/general/" class="icon icon-home"> Software Heritage - Documentation
+{%- endif %}
 
-{# copied from sphinx_rtd_theme/layout.html, with the extra System Administration link #}
+{%- if logo %}
+  {#- Not strictly valid HTML, but it's the only way to display/scale
+      it properly, without weird scripting or heaps of work
+  #}
+  {%- if sphinx_version_info < (4, 0) -%}
+  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
+  {%- else %}
+  <img src="{{ logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
+  {%- endif %}
+{%- endif %}
+</a>
+
+{%- if theme_display_version %}
+  {%- set nav_version = version %}
+  {%- if READTHEDOCS and current_version %}
+    {%- set nav_version = current_version %}
+  {%- endif %}
+  {%- if nav_version %}
+    <div class="version">
+      {{ nav_version }}
+    </div>
+  {%- endif %}
+{%- endif %}
+
+{%- include "searchbox.html" %}
+
+{%- endblock %}
+
+{# copied from sphinx_rtd_theme/layout.html, with the extra System Administration & "user documentation" links #}
 {%- block menu %}
   {%- set toctree = toctree(maxdepth=theme_navigation_depth|int,
                             collapse=theme_collapse_navigation|tobool,
@@ -33,6 +68,7 @@
   <hr />
 
   <ul>
+      <li class="toctree-l1"><a href="/user/">User Documentation</a></li>
       <li class="toctree-l1"><a href="/sysadm/">System Administration</a></li>
   </ul>
 {%- endblock %}

docs/contributing/index.rst

+.. _contributing:
+
 Contributing
 ============
 

docs/getting-started/index.rst

+.. _getting-started-home:
+
 Getting started
 ===============
 

docs/tutorials/index.rst

+.. _tutorials:
+
 Tutorials
 =========
 

general/.gitignore

+*-stamp
+_build/
+/swh-*
+sources/

general/Makefile

+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

general/_static

+../docs/_static
\ No newline at end of file

general/_templates/breadcrumbs.html

+{% extends "!breadcrumbs.html" %}
+
+{# Overrides RTD's default "View page source" link formatting, which
+   forces the full page name in the link; but we don't want it because
+   page names include the repo, eg. "swh-model/index".
+   The view_in_phabricator.py extension sets swh_source_url to
+   ".../source/swh-model/browse/master/docs/index"
+#}
+{%- block breadcrumbs_aside %}
+  <li class="wy-breadcrumbs-aside">
+    {%- if hasdoc(pagename) and display_vcs_links %}
+      <a href="{{ swh_source_url }}{{ page_source_suffix }}">{{ _('View page source') }}</a>
+    {% endif %}
+  </li>
+{%- endblock %}

general/_templates/layout.html

+{% extends "!layout.html" %}
+
+{% block extrahead %}
+<!-- Matomo -->
+<script type="text/javascript">
+  var _paq = window._paq = window._paq || [];
+  _paq.push(['trackPageView']);
+  (function() {
+    var u="https://piwik.inria.fr/";
+    _paq.push(['setTrackerUrl', u+'matomo.php']);
+    _paq.push(['setSiteId', '59']);
+    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
+    g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
+  })();
+</script>
+<!-- End Matomo Code -->
+{% endblock %}
+
+{%- block sidebartitle %}
+{%- if logo and theme_logo_only %}
+  <a href="/general/">
+{%- else %}
+  <a href="/general/" class="icon icon-home"> Software Heritage - Documentation
+{%- endif %}
+
+{%- if logo %}
+  {#- Not strictly valid HTML, but it's the only way to display/scale
+      it properly, without weird scripting or heaps of work
+  #}
+  {%- if sphinx_version_info < (4, 0) -%}
+  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
+  {%- else %}
+  <img src="{{ logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
+  {%- endif %}
+{%- endif %}
+</a>
+
+{%- if theme_display_version %}
+  {%- set nav_version = version %}
+  {%- if READTHEDOCS and current_version %}
+    {%- set nav_version = current_version %}
+  {%- endif %}
+  {%- if nav_version %}
+    <div class="version">
+      {{ nav_version }}
+    </div>
+  {%- endif %}
+{%- endif %}
+
+{%- include "searchbox.html" %}
+
+{%- endblock %}
+

general/conf.py

+from swh.docs.sphinx.conf import *  # noqa
+
+project = "Software Heritage - Documentation"

general/index.rst

+.. _swh-docs:
+
+Software Heritage documentation
+================================
+
+:ref:`User Documentation <swh-users:swh-docs>`
+----------------------------------------------
+
+    * :ref:`FAQ <swh-users:faq>`
+    * :ref:`Listers <swh-users:listers>`
+    * :ref:`Loaders <swh-users:loaders>`
+
+:ref:`Development Documentation <swh-devel:swh-docs>`
+-----------------------------------------------------
+
+    * :ref:`Getting started <swh-devel:getting-started-home>`
+    * :ref:`Software architecture <swh-devel:architecture>`
+    * :ref:`Contributing <swh-devel:contributing>`
+    * :ref:`Tutorials <swh-devel:tutorials>`
+    * :ref:`FAQ <swh-devel:faq>`
+    * :ref:`Roadmap <swh-devel:roadmap-current>`
+    * :ref:`API reference <swh-devel:api-reference>`
+    * :ref:`Archive ChangeLog <swh-devel:archive-changelog>`
+    * :ref:`Journal Specification <swh-devel:journal-specs>`
+
+:ref:`Sysadmin Documentation <swh-sysadm:swh-docs>`
+---------------------------------------------------
+
+    * :ref:`Puppet <swh-sysadm:puppet>`
+    * :ref:`Network Architecture <swh-sysadm:infrastructure>`
+    * :ref:`Server Architecture <swh-sysadm:server-architecture>`
+    * :ref:`Data Silos <swh-sysadm:data-silos>`
+    * :ref:`SWH Software Deployment <swh-sysadm:swh-software-deployment>`
+    * :ref:`User management <swh-sysadm:user-management>`
+    * :ref:`Life-cycle management <swh-sysadm:lifecycle-management>`
+    * :ref:`Mirror operations <swh-sysadm:mirror_operations>`
+    * :ref:`Support services <swh-sysadm:support-services>`
+
+
+.. toctree::
+  :maxdepth: 3
+  :caption: Contents:
+  :titlesonly:
+  :hidden:
+