Updated docs for maintainers (#179)

dgarcia360 · web-flow · commit d516948e1f87 · 2021-06-17T08:46:54.000+01:00
* Updated docs for maintainers

* Review comments

* Review comments
diff --git a/docs/source/commands.rst b/docs/source/commands.rst
@@ -20,42 +20,37 @@ To preview the docs:
 
 2. Open http://127.0.0.1:5500/ with your preferred browser.
 
-You can pass custom options to increase or decrease verbosity. For a list of all the available options, refer to the `Sphinx documentation <https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_.
-For example:
+.. tip:: You can pass custom options to increase or decrease verbosity. For a list with all the available options, refer to the `Sphinx documentation <https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_.
+
+To increase verbosity, use the option ``-v``:
 
 .. code:: console
 
     make preview SPHINXOPTS=-v
 
-Preview multiversion 
---------------------
-The multiversionpreview generates a local instance of the docs site with all specified versions available for navigation. You can view the rendering in a sandbox environment on your local browser. 
-To preview multiple versions:
-
-1. Build the docs.
+To decrease verbosity, use the option ``-Q``:
 
 .. code:: console
 
-    cd docs
-    make previewmultiversion
-
-2. Open http://0.0.0.0:5500/ with your preferred browser.
+    make preview SPHINXOPTS=-Q
 
-If the version drop-down menu does not contain the all of the listed versions, try to run ``git fetch --tags`` to download the latest tags from remote.
 
-Build HTML for the current branch
----------------------------------
+Preview multiversion 
+--------------------
 
-To generate an HTML version:
+The multiversionpreview command generates a local instance of the docs site with all :doc:`specified versions <../configuration/multiversion>` available for navigation.
+You can view the rendering in a sandbox environment on your local browser.
+To preview multiple versions:
 
 1. Build the docs.
 
 .. code:: console
 
     cd docs
-    make dirhtml
+    make multiversionpreview
+
+2. Open http://0.0.0.0:5500/ with your preferred browser.
 
-2. The previous command should generate HTML docs under the ``docs/_build/dirhtml`` directory.
 
 Build HTML for multiple versions
 --------------------------------
@@ -73,6 +68,8 @@ To generate multiple versions of the documentation:
 
 2. The previous command should generate HTML docs under the ``docs/_build/dirhtml`` directory.
 
+.. tip:: If the command raises an error, see :doc:`Troubleshooting <configuration/troubleshooting>` for help.
+
 Clean all builds
 ----------------
 
diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst
@@ -7,11 +7,13 @@ Configuration
    
    template
    multiversion
-   
+   troubleshooting
+
 .. panel-box::
   :title: Overview
   :id: "getting-started"
   :class: my-panel
 
   * :doc:`Template Options <template>` - Configuration options for this theme.
   * :doc:`Multiversion Options <multiversion>` - Configuration options for the multiversion extension.
+  * :doc:`Troubleshooting <multiversion>` - Help to resolve common issues.
diff --git a/docs/source/configuration/troubleshooting.rst b/docs/source/configuration/troubleshooting.rst
@@ -0,0 +1,58 @@
+===============
+Troubleshooting
+===============
+
+Multiversion
+------------
+
+.. _Sync_Fork:
+
+I cannot see my latest local changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the command builds the documentation that is available on GitHub (remote repository).
+
+To build multiversion docs for the local branches:
+
+1. In ``conf.py``, set ``smv_remote_whitelist`` to ``None``:
+
+.. code:: console
+
+    smv_remote_whitelist = None
+
+2. Follow `Syncing a Fork <https://docs.github.com/es/github/collaborating-with-pull-requests/working-with-forks/syncing-a-fork>`_ for every branch not updated in your fork.
+
+3. Run ``make multiversionpreview`` again.
+
+.. _Preview_Production:
+
+I want to preview the documentation published in production
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Follow `these steps <https://docs.github.com/es/github/collaborating-with-pull-requests/working-with-forks/syncing-a-fork>`_ to configure a remote that points to the upstream repository in Git.
+
+2. Download the latest tags and branches from upstream:
+
+.. code:: console
+
+    git fetch --all
+
+3. Edit the setting ``smv_remote_whitelist`` in the file `conf.py` to build the docs from upstream as follows:
+
+.. code:: console
+
+    smv_remote_whitelist = r"^upstream$"
+
+4. Run the command ``make multiversionpreview`` again.
+
+No matching refs found!
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If the console raises the error "No matching refs found!", most likely your fork is not updated with the upstream repository.
+
+In this case, you can:
+
+* Build multiversion docs for the upstream repository. See :ref:`Preview documentation published in production <Preview_Production>` (recommended)
+* Sync the fork with the upstream repository. See :ref:`Preview latest local changes <Sync_Fork>`
+
+Another frequent mistake that raises the error message is to have typos in the configuration file. Make sure that the version names listed in ``TAGS`` and ``BRANCHES`` settings from ``conf.py`` match the repository's branch and tags names on Git.
diff --git a/docs/source/contribute/contribute-docs.rst b/docs/source/contribute/contribute-docs.rst
@@ -216,7 +216,7 @@ Submit a pull request (PR)
 
 We expect that you are aware of how to submit a PR to GitHub. If you are not, please look at this `tutorial <https://guides.github.com/activities/hello-world/>`_.
 Every repository handles PRs differently. Some require you to use a template for submissions and some do not.
-Make sure to speak with your project’s maintainer before submitting the PR to avoid any misunderstanding or issues.
+Make sure to speak with the project’s maintainer before submitting the PR to avoid any misunderstanding or issues.
 
 If you are writing new content it is **highly recommended** to set your PR to a draft state.
 For Documentation PRs, the following guidelines should be applicable to all Scylla projects:
diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -12,6 +12,7 @@ Examples
    images
    links
    lists
+   markdown
    panel-box
    substitutions
    tables
@@ -31,6 +32,7 @@ Examples
   * :doc:`Images <images>`
   * :doc:`Links <links>`
   * :doc:`Lists <lists>`
+  * :doc:`Markdown <markdown>`
   * :doc:`Panel Box <panel-box>`
   * :doc:`Substitutions <substitutions>`
   * :doc:`Tables <tables>`
diff --git a/docs/source/examples/markdown.md b/docs/source/examples/markdown.md
@@ -0,0 +1,18 @@
+# Markdown Support
+
+The theme supports writing documents in MarkDown thanks to the extension [recommonmark](https://github.com/readthedocs/recommonmark).
+
+## MarkDown Cheatsheet
+
+For Markdown syntax reference, you can use this `Cheatsheet <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet>`_.
+
+## Using directives in MarkDown
+
+You can use all restructuredText directives with the ``eval_rst`` code block. Here's an example:
+
+``` rst
+    ```eval_rst
+    .. autoclass:: recommonmark.transform.AutoStructify
+        :show-inheritance:
+    ```
+```
diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -2,53 +2,47 @@
 Getting Started
 ===============
 
-This site is a guide for using ``sphinx-scylladb-theme`` in ScyllaDB documentation projects.
-
-The theme's source code is hosted on `GitHub <https://github.com/scylladb/sphinx-scylladb-theme>`_. 
-The repository also contains a `sample documentation project <https://github.com/scylladb/sphinx-scylladb-theme/tree/master/docs>`_ using this theme.
-
-Theme Features
---------------
-
-* Bundled as a `PyPI <https://pypi.org/project/sphinx-scylladb-theme/>`_ package for easier installation/upgrading.
-* Support for files written in Markdown and reStructuredText.
-* Compatible with `GitHub Pages <../github-pages>`_.
-* Build docs for `different versions <../configuration/multiversion>`_ of your project.
-* Shared search engine between documentation projects.
-
-Documentation
--------------
+For Docs Maintainers
+--------------------
 
 .. panel-box::
-  :title: For Docs Maintainers
+  :title: Documentation
   :id: "components"
   :class: my-panel
 
-  #. `Add Sphinx & theme to your project <installation>`_
-  #. `Configure the theme <../configuration/template>`_
-  #. `List new versions  <../configuration/multiversion>`_
-  #. `Publish to GitHub Pages  <../github-pages>`_
-  #. `Commands to build docs  <../commands>`_
+  * :doc:`Read about the toolchain <toolchain>`
+  * :doc:`Add Sphinx & theme to a project <installation>`
+  * :doc:`Configure the theme <../configuration/template>`
+  * :doc:`List new versions  <../configuration/multiversion>`
+  * :doc:`Publish to GitHub Pages  <../github-pages>`
+  * :doc:`Commands to build docs  <../commands>`
+
+For Docs Contributors
+---------------------
 
 .. panel-box::
-  :title: For Docs Contributors
+  :title: Documentation
   :id: "components"
   :class: my-panel
 
-  `Scylla Docs Contributor’s Handbook <../contribute/contribute-docs>`_
-  `Markup Guide for Docs Contributors <../contribute/markup-guide>`_
+  * :doc:`Scylla Docs Contributor’s Handbook <../contribute/contribute-docs>`
+  * :doc:`Markup Guide for Docs Contributors <../contribute/markup-guide>`
+
 
+For Theme Maintainers
+---------------------
 
 .. panel-box::
-  :title: For Theme Contributors
+  :title: Documentation
   :id: "components"
   :class: my-panel
 
-  `Contribute to the Theme <../contribute/contribute-theme>`_
+  :doc:`Contribute to the Theme <../contribute/contribute-theme>`
 
 .. toctree::
    :maxdepth: 2
    :glob:
    :hidden:
    
+   toolchain
    installation
diff --git a/docs/source/getting-started/installation.rst b/docs/source/getting-started/installation.rst
@@ -2,7 +2,7 @@
 Installation
 ============
 
-This guide explains how to install Sphinx and this theme in a ScyllaDB project.
+This guide explains how to add the documentation toolchain to a project hosted on GitHub.
 
 1. Copy the ``docs`` and ``.github`` directories from the repository `scylladb/sphinx-scylladb-theme <https://github.com/scylladb/sphinx-scylladb-theme>`_
 to the project root directory where you want to set up docs. The directory structure should look like this:
@@ -34,4 +34,3 @@ to the project root directory where you want to set up docs. The directory struc
 
 6. From the command line, run ``make preview`` within the ``docs`` folder. Fix any warnings raised by Sphinx. Once the docs build without errors, open ``http://127.0.0.1:5500/`` to preview the generated site.
 
-
diff --git a/docs/source/getting-started/toolchain.rst b/docs/source/getting-started/toolchain.rst
@@ -0,0 +1,59 @@
+=========
+Toolchain
+=========
+
+Here are some basic concepts you should know before adding the doc toolchain to a project.
+
+Markup language
+---------------
+
+Most docs are written in RestructuredText. RestructuredText is a file format for textual data used primarily for technical documentation.
+
+Alternatively, you can also use :doc:`MarkDown <../examples/markdown>` to create content pages.
+
+`Learn more <https://www.sphinx-doc.org/es/master/usage/restructuredtext/index.html>`__
+
+Sphinx
+------
+
+The tool we used to converts restructuredText and Markdown to HTML.
+Sphinx also has directives and extensions to add additional options for formatting the text.
+
+`Learn more <https://www.sphinx-doc.org>`__
+
+ScyllaDB Sphinx Theme
+---------------------
+
+The theme all Scylla documentation projects share to have a common look and feel.
+It also adds a set of custom functionallities available to make them available to all projects.
+
+`Learn more <https://github.com/scylladb/sphinx-scylladb-theme>`__
+
+Multiversion Extension
+----------------------
+
+The extension Scylla docs use to build docs for different versions.
+
+`Learn more <https://github.com/Holzhaus/sphinx-multiversion>`__
+
+GitHub
+------
+
+Hosts the code and docs source files of Scylla's proejcts.
+
+`Learn more <https://github.com>`__
+
+GitHub Pages
+------------
+
+Hosts the HTML version of the docs generated by Sphinx.
+
+`Learn more <https://pages.github.com/>`__
+
+GitHub Actions
+--------------
+
+Builds and deploys the documentation to GitHub Pages every time there is new content.
+All the repositories deploy the documentation automatically except the repository scylla-docs, which is deployed manually.
+
+`Learn more <https://docs.github.com/actions>`__
diff --git a/docs/source/github-pages.rst b/docs/source/github-pages.rst
@@ -9,17 +9,16 @@ When :doc:`multiversion <../configuration/multiversion>` is enabled, GitHub Page
 Enabling GitHub Pages
 ---------------------
 
-#. Create a file named ``.github/pages.yaml`` in your project's root repository.
+#. Create a file named ``.github/pages.yaml`` in the project's root repository.
 
 #. Copy the contents from `this file <https://github.com/scylladb/sphinx-scylladb-theme/blob/master/.github/workflows/pages.yml>`_ into ``.github/pages.yaml``.
 
-#. (Optional) If your repository default branch is not ``master``, edit the configuration file to use the default branch name instead.
+#. (Optional) If the repository default branch is not ``master``, edit the configuration file to use the default branch name instead.
 
 #. Commit and push the changes to GitHub (default branch).
 
 #. Wait a couple of minutes; it might take a while until GitHub builds the site. If everything goes well, you will see the docs published under ``https://scylladb.github.io/<repository-slug>``.
 
-
 Setting up a custom domain
 --------------------------
 
@@ -38,3 +37,14 @@ Disabling GitHub Pages
 
 To disable the docs deployment temporarily, see `Unpublishing a GitHub Pages Site <https://help.github.com/en/github/working-with-github-pages/unpublishing-a-github-pages-site#unpublishing-a-project-site>`_.
 
+Triggering builds manually
+---------------------------
+
+Re-running workflows is useful when:
+
+- The theme received an update. By running the last build manually, the documentation project will receive the latest version. Otherwise, the theme will be automatically updated when the default branch gets an update.
+
+- A previous version (branch or a tag) received a patch. Otherwise, the changes will not be reflected in production until the master branch gets an update.
+
+To re-run a workflow see, `Re-running a workflow <https://docs.github.com/en/actions/managing-workflow-runs/re-running-a-workflow>`_.
+
