diff --git a/docs/contributing/tutorial-docs-contribution.rst b/docs/contributing/tutorial-docs-contribution.rst index 54de1ad..3f0c306 100644 --- a/docs/contributing/tutorial-docs-contribution.rst +++ b/docs/contributing/tutorial-docs-contribution.rst @@ -1,145 +1,182 @@ +.. _doc-contribution: + Tutorial: Best practices when writing SWH docs ============================================== + A tutorial on how to contribute documentation into the Software Heritage world. Step 1: Identify your audience ------------------------------ #. Ask yourself: Who are the readers of the documentation that you are writing? -In the Software Heritage community we have identified three general types of personas that can be divided into sub-roles: + In the Software Heritage community, three general types of personas are + distinguished: + * **visitors**: people who want to know what is the SWH initiative and archive * **users**: people who want to use the SWH features - * as a service - * as a module by running a local instance - * **contributors**: people who are contributing to SWH - * as developers - * as sys-admins - * as support rôle -Contributors might be part of the SWH team or external contributors. + * as a service + * as a module by running a local instance + + * **contributors**: people who are contributing to SWH (either external or swh + staff) -#. use the persona type to determine the document's location in step 2 -#. add the intended audience on the top of the page to inform the + * as developers + * as sys-admins + * as support role -Step 2: Determine the location for the documentation ----------------------------------------------------- +#. use the persona type to determine the document location in step 2 -Information should have a permanent home as documentation. -Elements that are work in progress can live in the forge on issues or in hedgedoc, but these are not permanent locations. +#. add the intended audience on the top of the page + +Step 2: Determine the documentation location +-------------------------------------------- + +Information should have a permanent home as documentation. Elements that are work in +progress can live in the forge on issues or in hedgedoc, but these are not permanent +locations. #. Choose high-level location: -Here is a list of permanent locations: - * The WordPress website: for visitors - * The archive web-app: for visitors and users (of the interface or API) - * The Sphinx docs: - * *devel* for contributors - * *sysadm* for sys-admins - * *users* for users of the infrastructure and all the different services + +Possible permanent locations include: + +* The WordPress website: for visitors + +* The archive web-app: for visitors and users (of the interface or API) + +* The Sphinx docs: + + * *devel* for contributors + * *users* for users of the infrastructure and all the different services + * *sysadm* for sys-admins #. For contributors documentation in devel: - #. Choose if the subject is a high level (cross-module) section or in a specific module - * if the document is relative to only one module, go and add it in the /docs directory in the module - * for cross-module documentation, use the swh-docs repository and the appropriate sub-directory (e.g architecture) - #. Decide if a subsection is needed with multiple pages (tutorials, how-tos, reference or explanation). -#. For sys-admin (in sysadm folder) and user documentation (in users folder): - #. Verify if an existing section is already describing the theme that you want to document. - #. Decide if a subsection is needed with multiple pages (tutorials, how-tos, reference or explanation). + #. Choose if the subject is a high level (cross-module) section or in a specific + module + + * if the document is relative to only one module, go and add it in the */docs* + directory in the module + + * for cross-module documentation, use the swh-docs repository and the appropriate + sub-directory (e.g architecture) + #. Decide if a subsection is needed with multiple pages (tutorials, how-tos, + reference or explanation). -Step 3: Choose the type of documentation ----------------------------------------- +#. For sys-admin (in */sysadm* folder) and user documentation (in */users* folder): + #. Check if an existing section is already describing the theme that you want to + document. + #. Decide if a subsection is needed with multiple pages (tutorials, how-tos, + reference or explanation). + +Step 3: Choose documentation type +--------------------------------- We are following Divio's approach with four major types of documentation: -* Tutorial: allowing newcomers to get started and ease the onboarding contributors and users -* How to guide: show how to solve a specific problem in a step-by-step manner. The how to guide is practical to use. + +* Tutorial: allowing newcomers to get started and ease the onboarding contributors and + users. + +* How to: how to solve a specific problem in a step-by-step practical manual. + * Reference: theoretical/technical knowledge which is information oriented. -* Explanation: theoretical knowledge which is understanding oriented to analyze, discuss and explain different decisions, including background and context. + +* Explanation: theoretical knowledge which is understanding oriented to analyze, discuss +and explain different decisions, including background and context. For more information: https://documentation.divio.com/ And Daniele Procida presentation on: https://www.youtube.com/watch?v=t4vKPhjcMZg .. note:: We propose using in the following naming scheme depending on the type of document: * Tutorial: Tutorial name] * How to ... * Reference: [Reference name] * Explanation: [Explanation name] Step 4: Create a page or sub-section with multiple pages -------------------------------------------------------- -#. Create a *.rst* file with a short name of your doc in the approriate directory (see step 2). -If this is a sub-section, the first file should be an index.rst file containing the list of the current sub-section's files. -You should follow the empty page template below. -The template starts with a reference, so that you can link to this new page. -The name of the page should follow the scheme from step 3. -Then, you can link to an existing page that already contains nformation about the subject. +#. Create a *.rst* file with a short name of your doc in the approriate directory (see + step 2). If this is a sub-section, the first file should be an *index.rst* file + containing the list of the current sub-section files. + +#. For not yet ready page, you can create simply create an empty page using the template + below. The template starts with a reference, so that you can link to this new page + from elsewhere. The page name should follow the step 3. scheme. + +#. For existing page, you can link the new page with the existing one containing the + desired information. Empty page template ^^^^^^^^^^^^^^^^^^^ .. code-block:: rst - .. _empty_page: - Empty page - ========== + .. _empty_page: - .. todo:: - This page is a work in progress. For now, please refer to the `existing documentation `_. + Empty page + ========== -Empty subsection template + .. todo:: + This page is a work in progress. For now, please refer to the `existing documentation `_. + +Empty subsection template ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: rst - .. _empty_subsection: - Empty subsection - ================ + .. _empty_subsection: - .. toctree:: - :titlesonly: + Empty subsection + ================ - tutorial-my-first-tuto - howto-do-things - howto-test-stuff - howto-dance - reference-info - reference-best-practices + .. toctree:: + :titlesonly: + tutorial-my-first-tuto + howto-do-things + howto-test-stuff + howto-dance + reference-info + reference-best-practices README in module ^^^^^^^^^^^^^^^^ -We want to reduce redundancy in documentation as much as possible. -The option we should strive for is adding a symlink to docs/README.rst in the repo's module. -Furthermore, docs/README.rst should include docs/index.rst, as following: + +We want to reduce redundancy in documentation as much as possible. The option we should +strive for is adding a symlink to docs/README.rst in the repo's module. Furthermore, +docs/README.rst should include docs/index.rst, as following: .. code-block:: rst - .. _swh-fuse: - .. include:: README.rst + .. _swh-fuse: + + .. include:: README.rst + .. toctree:: + :maxdepth: 1 + :caption: Overview - .. toctree:: - :maxdepth: 1 - :caption: Overview + cli + configuration + Design notes + Tutorial - cli - configuration - Design notes - Tutorial - Step 5: Add link to page/sub-section from an index.rst ------------------------------------------------------ -Add the file-name to the menu of the parent index.rst +Add the file-name to the menu of the parent index.rst Step 6: Commit change for code review ------------------------------------- -You should open a diff for a documentation change following the instructions in :ref:`code-review` + +You should open a diff for a documentation change following the instructions in +:ref:`code-review` diff --git a/docs/index.rst b/docs/index.rst index c223f2e..42f95b4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,241 +1,242 @@ .. _swh-docs: Software Heritage - Development Documentation ============================================= Getting started --------------- * :ref:`getting-started` → deploy a local copy of the Software Heritage software stack in less than 5 minutes, or * :ref:`developer-setup` → get a working development setup that allows to hack on the Software Heritage software stack Contributing ------------ * :ref:`patch-submission` → learn how to submit your patches to the Software Heritage codebase * :ref:`code-review` → rules and guidelines to review code in Software Heritage * :ref:`python-style-guide` → how to format the Python code you write Architecture ------------ * :ref:`architecture-overview` → get a glimpse of the Software Heritage software architecture * :ref:`mirror` → learn what a Software Heritage mirror is and how to set up one * :ref:`Metadata workflow ` → learn how Software Heritage stores and handles metadata * :ref:`Keycloak ` → learn how to use Keycloak, the authentication system used by |swh|'s web interface and public APIs Data Model and Specifications ----------------------------- * :ref:`persistent-identifiers` Specifications of the SoftWare Heritage persistent IDentifiers (SWHID). * :ref:`data-model` Documentation of the main |swh| archive data model. * :ref:`journal-specs` Documentation of the Kafka journal of the |swh| archive. Tutorials --------- * :ref:`testing-guide` * :doc:`/tutorials/issue-debugging-monitoring` * :ref:`Listing the content of your favorite forge ` and :ref:`running a lister in Docker ` * :ref:`Add a new swh package ` +* :ref:`doc-contribution` Frequently Asked Questions -------------------------- .. toctree:: :maxdepth: 2 faq/index Roadmap ------- * :ref:`roadmap-2021` Engineering ----------- * :ref:`infrastructure` Components ---------- Here is brief overview of the most relevant software components in the Software Heritage stack, in alphabetical order. For a better introduction to the architecture, see the :ref:`architecture-overview`, which presents each of them in a didactical order. Each component name is linked to the development documentation of the corresponding Python module. :ref:`swh.auth ` low-level library used by modules needing keycloak authentication :ref:`swh.core ` low-level utilities and helpers used by almost all other modules in the stack :ref:`swh.counters ` service providing efficient estimates of the number of objects in the SWH archive, using Redis's Hyperloglog :ref:`swh.dataset ` public datasets and periodic data dumps of the archive released by Software Heritage :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.fuse ` Virtual file system to browse the Software Heritage archive, based on `FUSE `_ :ref:`swh.graph ` Fast, compressed, in-memory representation of the archive, with tooling to generate and query it. :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-git ` loader for `Git `_ repositories :ref:`swh.loader-mercurial ` loader for `Mercurial `_ repositories :ref:`swh.loader-svn ` loader for `Subversion `_ repositories :ref:`swh.loader-cvs ` loader for `CVS `_ repositories :ref:`swh.model ` implementation of the :ref:`data-model` to archive source code artifacts :ref:`swh.objstorage ` content-addressable object storage :ref:`swh.objstorage.replayer ` Object storage replication tool :ref:`swh.scanner ` source code scanner to analyze code bases and compare them with source code artifacts archived by Software Heritage :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.search ` search engine for the archive :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 :ref:`swh.web.client ` Python client for :ref:`swh.web ` 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). Archive ------- * :ref:`Archive ChangeLog `: notable changes to the archive over time Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * `URLs index `_ * :ref:`search` * :ref:`glossary` .. ensure sphinx does not complain about index files not being included .. toctree:: :maxdepth: 2 :caption: Contents: :titlesonly: :hidden: getting-started/index architecture/index contributing/index tutorials/index faq/index roadmap/roadmap-2021.rst infrastructure/index swh.auth swh.core swh.counters swh.dataset swh.deposit swh.fuse swh.graph swh.indexer swh.journal swh.lister swh.loader swh.model swh.objstorage swh.objstorage.replayer swh.scanner swh.scheduler swh.search swh.storage swh.vault swh.web swh.web.client archive-changelog journal Python modules autodocumentation