diff --git a/python-project-template/README.md.jinja b/python-project-template/README.md.jinja index 662b6f9..7629b46 100644 --- a/python-project-template/README.md.jinja +++ b/python-project-template/README.md.jinja @@ -10,3 +10,35 @@ you whether or not you'd like to display it! For more information about the project template see the [documentation](https://lincc-ppt.readthedocs.io/en/latest/). + +## Dev Guide - Getting Started + +Before installing any dependencies or writing code, it's a great idea to create a +virtual environment. LINCC-Frameworks engineers primarily use `conda` to manage virtual +environments. If you have conda installed locally, you can run the following to +create and activate a new environment. + +``` +>> conda create env -n python=3.10 +>> conda activate +``` + +Once you have created a new environment, you can install this project for local +development using the following commands: + +``` +>> pip install -e .'[dev]' +>> pre-commit install +>> conda install pandoc +``` + +Notes: +1) The single quotes around `'[dev]'` may not be required for your operating system. +2) `pre-commit install` will initialize pre-commit for this local repository, so + that a set of tests will be run prior to completing a local commit. For more + information, see the Python Project Template documentation on + [pre-commit](https://lincc-ppt.readthedocs.io/en/latest/practices/precommit.html) +3) Install `pandoc` allows you to verify that automatic rendering of Jupyter notebooks + into documentation for ReadTheDocs works as expected. For more information, see + the Python Project Template documentation on + [Sphinx and Python Notebooks](https://lincc-ppt.readthedocs.io/en/latest/practices/sphinx.html#python-notebooks) diff --git a/python-project-template/{% if include_docs %}docs{% endif %}/index.rst.jinja b/python-project-template/{% if include_docs %}docs{% endif %}/index.rst.jinja index 1d10fc3..3f46042 100644 --- a/python-project-template/{% if include_docs %}docs{% endif %}/index.rst.jinja +++ b/python-project-template/{% if include_docs %}docs{% endif %}/index.rst.jinja @@ -5,6 +5,43 @@ Welcome to {{package_name}}'s documentation! ======================================================================================== +Dev Guide - Getting Started +--------------------------- + +Before installing any dependencies or writing code, it's a great idea to create a +virtual environment. LINCC-Frameworks engineers primarily use `conda` to manage virtual +environments. If you have conda installed locally, you can run the following to +create and activate a new environment. + +.. code-block:: bash + + >> conda create env -n python=3.10 + >> conda activate + + +Once you have created a new environment, you can install this project for local +development using the following commands: + +.. code-block:: bash + + >> pip install -e .'[dev]' + >> pre-commit install + >> conda install pandoc + + +Notes: + +1) The single quotes around ``'[dev]'`` may not be required for your operating system. +2) ``pre-commit install`` will initialize pre-commit for this local repository, so + that a set of tests will be run prior to completing a local commit. For more + information, see the Python Project Template documentation on + `pre-commit `_. +3) Install ``pandoc`` allows you to verify that automatic rendering of Jupyter notebooks + into documentation for ReadTheDocs works as expected. For more information, see + the Python Project Template documentation on + `Sphinx and Python Notebooks `_. + + .. toctree:: :hidden: