Merge pull request #1551 from buildtesters/update_docs_on_dev_deps_in…

…stallation

Documentation update on installing dev dependencies

docs/contributing/build_documentation.rst

@@ -22,10 +22,10 @@ Setup
 
 buildtest documentation is located in top-level `docs <https://github.com/buildtesters/buildtest/tree/devel/docs>`_ directory.
 If you want to build the documentation you will need to make sure your python environment
-has all the packages defined in ``docs/requirements.txt``. If your environment
-is already setup as described in :ref:`installing_buildtest` then  you can skip this step.
+has all the packages defined in `docs/requirements.txt <https://github.com/buildtesters/buildtest/blob/devel/docs/requirements.txt>`_.
+If your environment setup, then you can skip this step.
 
-To install your python packages, you can run the following::
+To install python dependencies for documentation build, you can run the following::
 
   pip install -r docs/requirements.txt
 
@@ -38,7 +38,7 @@ To build your documentation, navigate to the `docs` directory and run the follow
   make clean
   make html
 
-It is best practice to run ``make clean`` to ensure sphinx will remove old html
+It's best practice to run ``make clean`` to ensure sphinx will remove old html
 content from previous builds, but it is ok to skip this step if you are
 making minor changes.
 
@@ -90,27 +90,35 @@ Generating Documentation Examples for Buildtest Tutorial
 The documentation examples for the buildtest tutorial are run inside the container image
 ghcr.io/buildtesters/buildtest_spack:latest which means that some of the example output needs to be generated manually. There
 is a script `doc-examples.py <https://github.com/buildtesters/buildtest/blob/devel/scripts/spack_container/doc-examples.py>`_ that
-is responsible for auto-generating the documentation examples inside the container. To get the container running along with the buildtest codebase you will need to run the
-following commands.
+is responsible for auto-generating the documentation examples inside the container.
+
+To get into the container along with the buildtest codebase you will need to run the following commands
 
 .. Note::
 
    You may need to `source /etc/profile` in your container if you see module command is not found.
 
+.. Note::
+
+    You will need to volume mount **$BUILDTEST_ROOT** into `/home/spack/buildtest` in-order to get buildtest code-base accessible inside the container.
+
+
 .. code-block:: console
 
     docker run -it -v  $BUILDTEST_ROOT:/home/spack/buildtest ghcr.io/buildtesters/buildtest_spack:latest
+
+Once you are in the container run the following commands
+
+.. code-block:: console
+
     cd /home/spack/buildtest
     source scripts/spack_container/setup.sh
 
-You will need to volume mount **$BUILDTEST_ROOT** into `/home/spack/buildtest` in-order to get buildtest code-base accessible inside
-the container.
-
-Once your setup is complete, you can auto-generate documentation examples by running the following ::
+Once your setup is complete, you can auto-generate documentation examples by running the following::
 
         buildtest tutorial-examples
 
-Alternatively, the script can also be invoked via python as shown below :: 
+Alternatively, the script can also be invoked via python as shown below::
 
         python scripts/spack_container/doc-examples.py
 

docs/contributing/code_contribution_guide.rst

@@ -173,7 +173,7 @@ Configuring Black Pre-Commit Hook
 
 To configure pre-commit hook, make sure you install `pre-commit <https://pre-commit.com/>`_ via
 ``pip install pre-commit``. The `pre-commit` utility should be available if you install
-extra dependencies from buildtest (``pip install -r docs/requirements.txt``).
+extra dependencies from buildtest (``pip install '.[dev]'``).
 
 The pre-commit hook configuration can be found in `.pre-commit-config.yaml <https://github.com/buildtesters/buildtest/blob/devel/.pre-commit-config.yaml>`_
 
@@ -271,8 +271,8 @@ pyflakes
 
 `pyflakes <https://pypi.org/project/pyflakes/>`_ is a program that checks for python source
 code for errors such as unused imports. We have configured an automated check to test your incoming PR using pyflakes.
-pyflakes should be available in your python environment if you installed buildtest extra
-dependencies in requirements.txt (``pip install -r docs/requirements.txt``).
+pyflakes should be available in your python environment if you installed the dev dependencies
+(``pip install '.[dev]'``).
 
 You can run pyflakes against any file or directory the ones of importance is running pyflakes against
 buildtest source code and regression test. You can do that by running::
@@ -282,8 +282,7 @@ buildtest source code and regression test. You can do that by running::
 Running yamllint
 ------------------
 
-We are using `yamllint <https://yamllint.readthedocs.io/en/stable/>`_, which is a linter for YAML files. This package can
-be installed when installing the development dependencies (``pip install -r docs/requirements.txt``). We have a
+We are using `yamllint <https://yamllint.readthedocs.io/en/stable/>`_, which is a linter for YAML files. We have a
 configuration file `.yamllint.yml <https://github.com/buildtesters/buildtest/blob/devel/.yamllint.yml>`_ used for configuring
 yamllint.
 

docs/installing_buildtest.rst

@@ -100,7 +100,7 @@ Development Dependencies (Optional)
 If you plan to contribute back to buildtest, you will need to install additional
 dependencies as follows::
 
-    $ pip install -r docs/requirements.txt
+    $ pip install -r '.[dev]'
 
 Usage (``buildtest --help``)
 ------------------------------