Skip to content

Commit 995d0e6

Browse files
author
Brad Crawford
committed
updated documentation, README, and added unit-tests for the local docs build.
1 parent cc6f7c6 commit 995d0e6

File tree

5 files changed

+539
-27
lines changed

5 files changed

+539
-27
lines changed

‎README.md‎

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Alternative software for `miniforge`:
2222
The python_github_tutorial package dependencies can be installed via conda, and this package tagged in conda via pip install:
2323

2424
To perform the python_github_tutorial package build, please run the following commands
25-
from the ``<YOUR_FILE_PATH/python_github_tutorial`` directory.
25+
from the ``<YOUR_FILE_PATH>/python_github_tutorial`` directory.
2626

2727
Create and install conda package:
2828

@@ -38,25 +38,29 @@ Activate the environment the environment
3838

3939
`conda activate python_github_tutorial`
4040

41-
Install the developement enviroment
41+
Install the developement environment
4242

4343
`pip install -e .`
4444

45-
Note: If you update the conda package, you may have to redo the pip install. Without doing this, it may allow incompatable versions of the dependencies to be installed, etc.:
45+
> [!NOTE]
46+
> If you update the conda package, you may have to redo the pip install. Without doing this, it may allow incompatable versions of the dependencies to be installed, etc.:
4647
4748

4849
## Run the example
4950

50-
This is an example of the supplimentary functions in the utils directory (``<YOUR_FILE_PATH/python_github_tutorial/python_github_tutorial/utils``) and the main function in the main_functions directory (``<YOUR_FILE_PATH/python_github_tutorial/python_github_tutorial/main_functions``).
51+
This is an example of the supplimentary functions in the utils directory (``<YOUR_FILE_PATH>/python_github_tutorial/python_github_tutorial/utils``) and the main function in the main_functions directory (``<YOUR_FILE_PATH>/python_github_tutorial/python_github_tutorial/main_functions``).
52+
The example (``examples.py``) is located here ``<YOUR_FILE_PATH>/python_github_tutorial/examples_to_run``. The instructions to run it are provided below:
5153

52-
The example is located here ``<YOUR_FILE_PATH/python_github_tutorial/examples_to_run``. The instructions to run it are provided below:
54+
The example is located here ``<YOUR_FILE_PATH>/python_github_tutorial/examples_to_run``. The instructions to run it are provided below:
5355

5456
`cd examples_to_run`
5557

5658
`python examples.py`
5759

5860
## Run the interactive example in Visual Studios Code (VScode)
5961

62+
This interactive example (``interactive_examples.py``) is located here ``<YOUR_FILE_PATH>/python_github_tutorial/examples_to_run``.
63+
6064
This is the same example but running it as an interactive job (i.e., like a Jupyter notebook). The example is located here 'examples_to_run/interactive_examples.py'.
6165

6266
When using Visual Studios Code (VScode), the '# %%' above each section makes it a cell, which can be run individually by holding shift and pressing enter.
@@ -69,7 +73,7 @@ The unit tests via ``pytest`` ensure that the code is build properly, running co
6973
accurate results.
7074

7175
To perform these tests (unit tests) for the python_github_tutorial package, please run the following commands
72-
from the ``<YOUR_FILE_PATH/python_github_tutorial/python_github_tutorial/tests`` directory:
76+
from the ``<YOUR_FILE_PATH>/python_github_tutorial/python_github_tutorial/tests`` directory:
7377

7478
Run all the tests:
7579

@@ -89,22 +93,31 @@ Run individual test on 'test_main_functions.py':
8993

9094
`pytest test_main_functions.py`
9195

96+
Run individual test on 'test_docs_build.py':
97+
98+
`cd python_github_tutorial/tests`
99+
100+
`pytest test_docs_build.py`
101+
92102
## Build the documentation (docs)
93103

94104
Building these HTML files locally via sphinx, which will allow you to access them with your
95105
local internet browsing application or HTML viewer (chrome, safari, VScode, etc.).
96-
The HTML files will be located in the ``<YOUR_FILE_PATH/python_github_tutorial/docs/_build/html`` directory after they are built.
106+
After the files are built, the HTML files will be located in the ``<YOUR_FILE_PATH>/python_github_tutorial/docs/_build/html`` directory after they are built.
97107

98108
The python_github_tutorial utilizes [sphinx](https://www.sphinx-doc.org/en/master/index.html) to construct the documentation.
99-
The user can build the documentation locally by executing the following command from the ``docs`` directory:
100109

101-
To perform the documents (docs) build for the python_github_tutorial package, please run the following commands
102-
from the ``<YOUR_FILE_PATH/python_github_tutorial/docs`` directory:
110+
The user can build the documentation locally by executing the following command from the ``docs`` directory.
111+
To perform the documents (docs) build for the python_github_tutorial package, please run the following commands from the ``<YOUR_FILE_PATH>/python_github_tutorial/docs`` directory:
112+
113+
103114

104115
`conda activate python_github_tutorial`
105116

106117
`cd docs`
107118

108119
`make html`
109120

121+
After the files are built, the HTML files will be located in the ``<YOUR_FILE_PATH>/python_github_tutorial/docs/_build/html`` directory after they are built.
122+
110123
You can find the docs `html` build here -> `docs/_build/html`. When in the `docs/_build/html` directory, click on any `html` file and it will open the full docs.

‎docs/getting_started/installation/installation.rst‎

Lines changed: 89 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,20 @@ Installation
44

55
Install an editable version from the source (GitHub)
66
----------------------------------------------------
7+
8+
This project's environment can be built using ``miniforge``.
9+
Alternative software for ``miniforge``:
10+
- You use can use ``anaconda`` or ``miniconda``, which use the same ``conda`` command.
11+
- You use can use ``micromamba`` or ``mamba``, supplimenting ``micromamba`` or ``mamba`` respectively for ``conda`` when using them.
12+
13+
The python_github_tutorial package dependencies can be installed via conda, and this package tagged in conda via pip install:
14+
15+
To perform the python_github_tutorial package build, please run the following commands
16+
from the ``<YOUR_FILE_PATH>/python_github_tutorial`` directory.
17+
718
::
819

9-
$ cd path_to_first_python_github_tutorial_dirctory_with_environment_yml_file
20+
$ cd python_github_tutorial
1021

1122
$ conda env create -f environment.yml
1223

@@ -15,31 +26,99 @@ Install an editable version from the source (GitHub)
1526
$ pip install -e .
1627

1728

29+
.. note::
30+
31+
If you update the conda package, you may have to redo the pip install. Without doing this, it may allow incompatable versions of the dependencies to be installed, etc.:
32+
33+
34+
Run the Example
35+
---------------
36+
37+
This is an example of the supplimentary functions in the utils directory (``<YOUR_FILE_PATH>/python_github_tutorial/python_github_tutorial/utils``) and the main function in the main_functions directory (``<YOUR_FILE_PATH>/python_github_tutorial/python_github_tutorial/main_functions``).
38+
The example (``examples.py``) is located here ``<YOUR_FILE_PATH>/python_github_tutorial/examples_to_run``. The instructions to run it are provided below:
39+
40+
::
41+
42+
$ cd examples_to_run
43+
44+
$ python examples.py
45+
46+
Run the Interactive Example in Visual Studios Code (VScode)
47+
-----------------------------------------------------------
48+
49+
This interactive example (``interactive_examples.py``) is located here ``<YOUR_FILE_PATH>/python_github_tutorial/examples_to_run``.
50+
51+
This is the same example but running it as an interactive job (i.e., like a Jupyter notebook). The example is located here 'examples_to_run/interactive_examples.py'.
52+
53+
When using Visual Studios Code (VScode), the '# %%' above each section makes it a cell, which can be run individually by holding shift and pressing enter.
54+
55+
1856
Building the HTML documenation files (GitHub)
1957
---------------------------------------------
2058

21-
Building these HTML files locally via sphinx, which will allow you to access them with your
22-
local internet browsing application or HTML viewer (chrome, safari, VScode, etc.).
23-
The HTML files will be located in the ``docs/_build/html`` directory after they are built.
59+
Building these HTML files locally via sphinx, which will allow you to access them with your
60+
local internet browsing application or HTML viewer (chrome, safari, VScode, etc.).
2461

2562
The python_github_tutorial utilizes `sphinx <https://www.sphinx-doc.org/en/master/index.html>`_ to construct the documentation.
26-
The user can build the documentation locally by executing the following command from the ``docs`` directory::
63+
64+
The user can build the documentation locally by executing the following command from the ``docs`` directory.
65+
To perform the documents (docs) build for the python_github_tutorial package, please run the following commands from the ``<YOUR_FILE_PATH>/python_github_tutorial/docs`` directory:
66+
67+
::
2768
2869
$ conda activate python_github_tutorial
2970
71+
$ cd docs
72+
3073
$ make html
3174

3275

76+
After the files are built, the HTML files will be located in the ``<YOUR_FILE_PATH>/python_github_tutorial/docs/_build/html`` directory after they are built.
77+
78+
You can find the docs `html` build here -> `docs/_build/html`. When in the `docs/_build/html` directory, click on any `html` file and it will open the full docs.
79+
80+
3381
Testing the software installation
3482
----------------------------------
3583

3684
The python_github_tutorial software tests the installation using `pytest <https://docs.pytest.org/en/stable/>`_.
3785
The unit tests via ``pytest`` ensure that the code is build properly, running correctly and producing
3886
accurate results.
3987

40-
To perform these tests (unit tests) for the python_github_tutorial package, please run the following commands
41-
from the ``python_github_tutorial/tests`` directory::
88+
To perform these tests (unit tests) for the python_github_tutorial package, please run the following commands
89+
from the ``<YOUR_FILE_PATH>/python_github_tutorial/python_github_tutorial/tests`` directory:
4290

43-
$ conda activate python_github_tutorial
44-
45-
$ pytest -v
91+
92+
Run all the tests:
93+
94+
::
95+
96+
$ cd python_github_tutorial/tests
97+
98+
$ pytest -v
99+
100+
101+
Run individual test on 'test_math.py':
102+
103+
::
104+
105+
$ cd python_github_tutorial/tests
106+
107+
$ pytest test_math.py
108+
109+
110+
Run individual test on 'test_main_functions.py':
111+
112+
::
113+
114+
$ cd python_github_tutorial/tests
115+
116+
$ pytest test_main_functions.py
117+
118+
Run individual test on 'test_docs_build.py':
119+
120+
::
121+
122+
$ cd python_github_tutorial/tests
123+
124+
$ pytest test_docs_build.py

‎docs/index.rst‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This Github tutorial shows the following:
1212

1313
* Code structure in a GitHub repository.
1414
* Setup and building GitHub documentation.
15-
* Basic structure and docstring (code documentation) for Python functions and classes.
15+
* Basic structure and docstrings for Python functions and classes.
1616

1717

1818
Code structure in a GitHub repository
@@ -32,21 +32,22 @@ Setup and building GitHub documentation
3232
---------------------------------------
3333

3434
This Github repository shows a simple example of how GitHub documentation is created via sphinx.
35-
This documentation can be build via `readthedocs <https://about.readthedocs.com/?ref=dotorg-homepage>`_
36-
for everyone to find on the internet.
37-
This documentation can also be build locally via ``sphinx`` and the ``make html`` command in the ``docs``
35+
This documentation can also be build locally via `sphinx <https://www.sphinx-doc.org/en/master/>`_ and the ``make html`` command in the ``docs``
3836
directory, which builds the html files locally that can be viewed in your local
37+
This documentation can be build via `readthedocs <https://about.readthedocs.com/?ref=dotorg-homepage>`_
38+
for everyone to find on the internet using the same files and structure.
3939
internet browsing application or html viewer (chrome, safari, VScode, etc.).
4040

4141

42-
Basic structure and docstring (code documentation) for Python functions and classes
43-
-----------------------------------------------------------------------------------
42+
Basic structure and docstrings for Python functions and classes
43+
---------------------------------------------------------------
4444

4545
This Github repository demonstrates how to write object-oriented Python code using classes and functions.
4646
In addition to the code structure itself, it is also an example of how to write Python docstrings.
4747
Python docstrings are the documentation for the classes and functions, which describe the
4848
input variables, attributes, methods, and outputs/output variables.
4949

50+
5051
.. toctree::
5152
:caption: Overview
5253
:maxdepth: 2

‎docs/reference/units.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,16 @@
22
Units
33
=====
44

5-
In this python_github_tutorial package, the input and output values are unitless (i.e., no units were used).
5+
In this ``python_github_tutorial`` package, the input and output values are unitless (i.e., no units were used).
66

77
If units were used in your software, you should specify them here and how they are utilized.
88
This includes specifiying the unitless variables, so the user knows. A good code will test for
99
the unit values and unitless values, minimizing user input error.
1010

1111
.. note::
12+
13+
Scientists and Engineers may find this ``unyt`` python package useful.
14+
1215
The `unyt <https://unyt.readthedocs.io/en/stable/>`_ can automatically convert units
1316
for you so the users can input any units, provided they are in the proper form.
1417
If the ``unyt`` package is used, it should be mentioned here, specifying where and

0 commit comments

Comments
 (0)