diff --git a/docs/dev/docs.rst b/docs/dev/docs.rst index fea0f692e58..81cf338bbed 100644 --- a/docs/dev/docs.rst +++ b/docs/dev/docs.rst @@ -6,19 +6,19 @@ the documentation for Read the Docs is built using Sphinx and hosted on Read the The docs are kept in the ``docs/`` directory at the top of the source tree, and are divided into developer and user-facing documentation. -Contributing through the Github UI +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. +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 +#. Click the checkmark next to your commit and it will expand to have multiple options. -#. click the "details" link next to the "docs/readthedocs.org:docs" item +#. 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 +#. Navigate to the section of the documentation you worked on to verify your changes. Contributing from your local machine ------------------------------------ @@ -26,14 +26,14 @@ Contributing from your local machine 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: +#. Clone the `readthedocs.org` repository: .. code-block:: console $ git clone --recurse-submodules https://github.com/readthedocs/readthedocs.org/ -#. create a virtual environment with Python 3.8 - (preferably the latest release, 3.8.12 at the time of writing), +#. Create a virtual environment with Python 3.8 + (preferably the latest release), activate it, and upgrade pip: .. code-block:: console @@ -43,14 +43,14 @@ you may want to verify those changes locally before pushing upstream. $ source .venv/bin/activate (.venv) $ python -m pip install -U pip -#. install documentation requirements +#. Install the documentation requirements: .. code-block:: console (.venv) $ pip install -r requirements/testing.txt (.venv) $ pip install -r requirements/docs.txt -#. build the documents +#. Build the documents: To build the user-facing documentation: @@ -66,4 +66,4 @@ you may want to verify those changes locally before pushing upstream. (.venv) $ cd docs (.venv) $ RTD_DOCSET=dev 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. +#. Check the changes locally at http://127.0.0.1:4444/ (rebuilds each time you edit and save a file).