Skip to content

Commit 1d9f988

Browse files
jasondegrawjasondegraw
authored
Merge pull request #3 from building-physics/add-sphinx
Add Sphinx documentation
2 parents ca3645d + a71b264 commit 1d9f988

16 files changed

+296
-1
lines changed

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/conf.py

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'airnet'
10+
copyright = '2023-present, Oak Ridge National Laboratory, managed by UT-Battelle'
11+
author = 'Jason W. DeGraw'
12+
release = '1.2.0'
13+
14+
# -- General configuration ---------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16+
17+
extensions = ['sphinx.ext.napoleon']
18+
19+
templates_path = ['_templates']
20+
exclude_patterns = []
21+
22+
23+
24+
# -- Options for HTML output -------------------------------------------------
25+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
26+
27+
html_theme = 'pydata_sphinx_theme'
28+
html_static_path = ['_static']

‎docs/source/contributing.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
Contributing
4+
============
5+
6+
To be completed.

‎docs/source/developers.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
Developers Guide
4+
================
5+
6+
.. toctree::
7+
devenv
8+
testing
9+
contributing
10+
:maxdepth: 2
11+
:caption: Contents:

‎docs/source/devenv.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
Development Environment
4+
=======================
5+
6+
.. _setup_hatch:
7+
8+
Hatch Environment Setup
9+
-----------------------
10+
11+
To set up a development environment using hatch, first install `hatch` with pip:
12+
13+
.. code-block:: console
14+
15+
$ pip install hatch
16+
17+
Clone the `repository <https://github.com/building-physics/airnet-python/>`_ to the location of your choice and start up a terminal in the
18+
root folder of the repo. Execute the following to generate an environment that has everything that is needed:
19+
20+
.. code-block:: console
21+
22+
$ hatch env create
23+
24+
To make sure that everything has worked, run
25+
26+
.. code-block:: console
27+
28+
$ hatch shell
29+
30+
to enter the environment that was created, and then execute
31+
32+
.. code-block:: console
33+
34+
$ airnetsim --help
35+
36+
You should see the help output from the program.
37+
38+
.. _vscode:
39+
40+
Using Visual Studio Code
41+
------------------------
42+
43+
To point Visual Studio Code at the created environment, find the environment with
44+
45+
.. code-block:: console
46+
47+
$ hatch run python -c "import sys;print(sys.executable)"
48+
49+
and copy the result. In Visual Studio Code, hit `ctrl-shift-P` to bring up the command palette, select "Python: Select Interpreter", and paste in the result from above. Any warnings (yellow squiqqly underlines) in the source files should go away.

‎docs/source/index.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.. airnet documentation master file, created by
2+
sphinx-quickstart on Thu Aug 1 21:21:42 2024.
3+
4+
:html_theme.sidebar_secondary.remove:
5+
6+
airnet documentation
7+
====================
8+
9+
**airnet** is a Python library implementing a pressure network solution in the spirit of the NIST AIRNET program,
10+
particularly with respect to the airflow elements. It is intended to operate similarly, but may not operate
11+
exactly the same due to implementation differences.
12+
13+
.. toctree::
14+
overview
15+
user_guide
16+
reference
17+
developers
18+
:maxdepth: 2
19+
:caption: Contents:
20+

‎docs/source/input.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
Defining the Network
4+
====================
5+
6+
.. _programmatic:
7+
8+
Programmatic Definition
9+
-----------------------
10+
11+
To be completed.
12+
13+
.. _input_file:
14+
15+
Network Definition File
16+
-----------------------
17+
18+
To be completed.

‎docs/source/install.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
.. _installation:
4+
5+
Installation
6+
------------
7+
8+
The airnet package is available for PyPi, and is installable via pip:
9+
10+
.. code-block:: console
11+
12+
$ pip install airnet
13+
14+
This installs the airnet package and two programs: :ref:`airnetsim <airnetsim>` and
15+
:ref:`summarize_airnet_input <summarize_airnet_input>`.

‎docs/source/overview.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
Overview
4+
========
5+
6+
To be completed.

‎docs/source/reference.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
API Reference
4+
=============
5+
6+
To be completed.
7+
8+
.. toctree::
9+
:maxdepth: 2
10+
:caption: Contents:

‎docs/source/running.rst

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
Running
4+
=======
5+
6+
The package provides two programs for use on :ref:`network input files <input_file>`.
7+
8+
.. _airnetsim:
9+
10+
airnetsim
11+
---------
12+
13+
.. code-block:: console
14+
15+
$ airnetsim --help
16+
usage: airnetsim [-h] [-v] NETWORK_FILE
17+
18+
Simulate airflow in an AIRNET network.
19+
20+
positional arguments:
21+
NETWORK_FILE
22+
23+
options:
24+
-h, --help show this help message and exit
25+
-v, --verbose operate verbosely
26+
27+
.. _summarize_airnet_input:
28+
29+
summarize_airnet_input
30+
----------------------
31+
32+
.. code-block:: console
33+
34+
$ summarize_airnet_input --help
35+
usage: summarize_airnet_input [-h] [-v] NETWORK_FILE
36+
37+
Summarize an AIRNET network input file.
38+
39+
positional arguments:
40+
NETWORK_FILE
41+
42+
options:
43+
-h, --help show this help message and exit
44+
-v, --verbose operate verbosely

‎docs/source/testing.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
Testing
4+
=======
5+
6+
.. _unit_tests:
7+
8+
Unit Tests
9+
----------
10+
11+
To be completed.
12+
13+
.. _regression_tests:
14+
15+
Regression Tests
16+
----------------
17+
18+
To be completed.

‎docs/source/user_guide.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
:html_theme.sidebar_secondary.remove:
2+
3+
User Guide
4+
==========
5+
6+
The airnet package provides a Python library and two programs for working with pressure network models.
7+
8+
.. toctree::
9+
install
10+
running
11+
input
12+
:maxdepth: 2
13+
:caption: Contents:

‎pyproject.toml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@ path = "src/airnet/__about__.py"
4444
dependencies = [
4545
"pytest",
4646
"pytest-cov",
47+
"sphinx",
48+
"pydata-sphinx-theme"
4749
]
4850
[tool.hatch.envs.default.scripts]
4951
cov = "pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=src/airnet --cov=tests {args}"

‎src/airnet/__about__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# SPDX-FileCopyrightText: 2023-present Oak Ridge National Laboratory, managed by UT-Battelle
22
#
33
# SPDX-License-Identifier: BSD-3-Clause
4-
__version__ = '1.1.0'
4+
__version__ = '1.2.0'

0 commit comments

Comments
 (0)