Improve documentation on contributing to documentation

docs/development/docs.rst

@@ -10,27 +10,84 @@ The docs are kept in the ``docs/`` directory at the top of the source tree.
    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
+#. navigate to the section of the documentation you worked on to verify your changes
+
+Contributing from your local machine
+------------------------------------
+
+.. note::
+
+    As of April 2021, you must use python 3.7 or lower 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
+
+   Run the `tox` command below to install the requirements.
+   More information about the `docs` option can be found on :ref:`development tests <development/tests:Testing>` section.
+
+   .. prompt:: bash
+
+      cd readthedocs.org
+      tox -e docs
+
+   Alternatively, you can try running the following commands if the `tox` command does not work for you.
+
+   .. 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 html
+
+#. the documents will be available in the `_build` folder.
+   Double-click the `index.html` file to open the documentation in a webpage
+
+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).