Merge pull request #8082 from cocobennett/improve-docs

Improve documentation on contributing to documentation

Author: astrojuanlu

docs/development/docs.rst

@@ -5,32 +5,77 @@ As one might expect,
 the documentation for Read the Docs is built using Sphinx and hosted on Read the Docs.
 The docs are kept in the ``docs/`` directory at the top of the source tree.
 
-.. TODO: expand this section explaining there the PR is automatically built and
-   the author can visualize changes without installing anything on their system.
-   However, if there is going to be periodic/bigger contributions, it may be a
-   good idea to install the Sphinx requirements to build our docs.
+Contributing through the Github UI
+----------------------------------
+
+If you're making small changes to the documentation,
+you can verify those changes through the documentation generated when you open a PR and can be accessed using the Github UI.
+
+#. click the checkmark next to your commit and it will expand to have multiple options
+
+#. right-click the "details" link next to the "docs/readthedocs.org:docs" item
+
+   .. image:: /img/details_link.png
+
+#. navigate to the section of the documentation you worked on to verify your changes
+
+Contributing from your local machine
+------------------------------------
+
+.. note::
+
+   You must use python 3.6 to generate the documentation.
+
+If you're making large changes to the documentation,
+you may want to verify those changes locally before pushing upstream.
+
+#. clone the `readthedocs.org` repository:
+
+   .. prompt:: bash
+
+      git clone --recurse-submodules https://github.com/readthedocs/readthedocs.org/
+
+#. install documentation requirements
+
+   .. prompt:: bash
+
+      cd readthedocs.org
+      pip install -r requirements/testing.txt
+      pip install -r requirements/docs.txt
+
+#. build the documents
+
+   .. prompt:: bash
+
+      cd docs
+      make livehtml
+
+#. the documents will be available at http://127.0.0.1:4444/ and will rebuild each time you edit and save a file.
+
+Guidelines
+----------
 
 Please follow these guidelines when updating our docs.
 Let us know if you have any questions or something isn't clear.
 
 The brand
----------
+^^^^^^^^^
 
 We are called **Read the Docs**.
 The *the* is not capitalized.
 
 We do however use the acronym **RTD**.
 
 Titles
-------
+^^^^^^
 
 For page titles, or Heading1 as they are sometimes called, we use title-case.
 
 If the page includes multiple sub-headings (H2, H3),
 we usually use sentence-case unless the titles include terminology that is supposed to be capitalized.
 
 Content
--------
+^^^^^^^
 
 * Do not break the content across multiple lines at 80 characters,
   but rather break them on semantic meaning (e.g. periods or commas).

docs/img/details_link.png

@@ -27,6 +27,7 @@ sphinx-prompt==1.4.0
 sphinx-notfound-page==0.6
 commonmark==0.9.1
 recommonmark==0.7.1
+sphinx-autobuild==2021.3.14
 
 # Linting
 rstcheck==3.3.1