Skip to content

Commit 6428f52

Browse files
AdamRJensenAdamRJensen
authored
Merge pull request #9 from AdamRJensen/sphinx
Setup sphinx and automatic documentation
2 parents f8644c7 + 184a464 commit 6428f52

25 files changed

+1999
-1577
lines changed

‎.gitignore‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
.ipynb_checkpoints
22
.vscode
33
*/.ipynb_checkpoints/*
4-
__pycache__/*
5-
test_file.csv
4+
__pycache__/
5+
6+
# Distribution / packaging
7+
*/build/
8+
*.egg-info/
9+
10+
# generated documentation
11+
docs/source/generated

‎.readthedocs.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
version: 2
2+
3+
conda:
4+
environment: docs/environment.yml
5+
6+
build:
7+
image: latest
8+
9+
# This part is necessary otherwise the project is not built
10+
python:
11+
version: 3.7
12+
install:
13+
- method: pip
14+
path: .
15+
16+
# By default readthedocs does not checkout git submodules
17+
submodules:
18+
include: all

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
BSD 3-Clause License
22

3-
Copyright (c) 2021, Adam R. Jensen
3+
Copyright (c) 2021-2022, twoaxistracking Development Team
44
All rights reserved.
55

66
Redistribution and use in source and binary forms, with or without

‎README.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,28 @@
11
# Open source code for calculating self-shading of two-axis tracking solar collectors
2-
This repository contains Python code for simulation self-shading in fields of two-axis solar trackers.
2+
"twoaxistracking" is a python package for simulating self-shading in fields of two-axis trackers.
33

4-
The two main functions are `generate_field_layout` and `two_axis_shading_fraction`. The function `generate_field_layout` calculates the collector locations for a user-defined regular field layout. For an introduction to regular field layouts and the defining parameters, please see the paper by [Cumpston and Pye (2014)](https://doi.org/10.1016/j.solener.2014.06.012).
4+
## Documentation
5+
The documentation can be found at [readthedocs](https://twoaxistracking.readthedocs.io/).
56

6-
The function `two_axis_shading_fraction` is used to calculate the shading fraction based on a specific field layout, aperture geometry, and solar position. Check out the [example tutorial](https://github.com/AdamRJensen/two_axis_tracker_shading/blob/main/notebooks/Example%20time%20series%20generation.ipynb) to get started! Alternatively, each function is documented according to the numpydoc style guide.
7+
## Installation and dependencies
8+
The package can be installed using pip:
79

10+
pip install twoaxistracking
811

9-
## Dependencies
1012
The main non-standard dependency is `shapely`, which handles the geometric operations. It is recommended to install `shapely` using conda, which can be done by executing the following command in an Anaconda Prompt:
1113

1214
conda install shapely
1315

14-
The solar modeling library `pvlib` is recommended for calculating the solar position and can similarly be installed by the command:
16+
The solar modeling library `pvlib` is recommended for calculating the solar position and can be installed by the command:
1517

16-
conda install -c conda-forge pvlib-python
18+
## Citing
19+
If you use the package in published work, please cite:
20+
> Adam R. Jensen et al. 2022.
21+
> "Self-shading of two-axis tracking solar collectors: Impact of field layout, latitude, and aperture shape."
22+
> Accepted in Solar Energy.
1723
1824
## Contributing
1925
Contributions to the repository, e.g., bug fixes and improvements to speed up the code are more than welcome.
2026

21-
2227
## License
2328
BSD 3-clause.

‎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/environment.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
name: readthedocs
2+
channels:
3+
- defaults
4+
- conda-forge
5+
dependencies:
6+
- python=3.7
7+
- pandas
8+
- matplotlib
9+
- numpy
10+
- shapely # Should be installed with conda
11+
- sphinx
12+
- pip:
13+
- pvlib
14+
- myst-nb
15+
- sphinx-book-theme

‎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+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.https://www.sphinx-doc.org/
25+
exit /b 1
26+
)
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/_static/twoaxistracking_logo.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/source/conf.py‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
import os
13+
import sys
14+
sys.path.insert(0, os.path.abspath('../../'))
15+
16+
# -- Project information -----------------------------------------------------
17+
18+
project = 'Two-axis tracking'
19+
copyright = '2021-2022, twoaxistracking Development Team'
20+
author = 'twoaxistracking Development Team'
21+
22+
23+
# -- General configuration ---------------------------------------------------
24+
25+
# Add any Sphinx extension module names here, as strings. They can be
26+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
27+
# ones.
28+
extensions = [
29+
'myst_nb', # markdown and jupyter-notebook parsing
30+
'sphinx.ext.autodoc', # generate documentation from docstrings
31+
'sphinx.ext.autosummary',
32+
'sphinx.ext.intersphinx',
33+
'sphinx.ext.napoleon', # parsing of Numpy docstrings
34+
]
35+
36+
# Add any paths that contain templates here, relative to this directory.
37+
# templates_path = ['_templates']
38+
39+
# List of patterns, relative to source directory, that match files and
40+
# directories to ignore when looking for source files.
41+
# This pattern also affects html_static_path and html_extra_path.
42+
exclude_patterns = []
43+
44+
45+
# -- Options for HTML output -------------------------------------------------
46+
47+
# The theme to use for HTML and HTML Help pages. See the documentation for
48+
# a list of builtin themes.
49+
html_theme = 'sphinx_book_theme'
50+
html_title = 'Two-axis tracking'
51+
html_logo = "_static/twoaxistracking_logo.svg"
52+
html_favicon = "_static/twoaxistracking_logo.svg"
53+
54+
# Add any paths that contain custom static files (such as style sheets) here,
55+
# relative to this directory. They are copied after the builtin static files,
56+
# so a file named "default.css" will overwrite the builtin "default.css".
57+
html_static_path = ['_static']
58+
59+
# The name of the Pygments (syntax highlighting) style to use.
60+
pygments_style = 'sphinx'
61+
62+
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
63+
html_show_copyright = False
64+
65+
# Example configuration for intersphinx: refer to the Python standard library.
66+
intersphinx_mapping = {
67+
'python': ('https://docs.python.org/3/', None),
68+
'numpy': ('https://numpy.org/doc/stable/', None),
69+
'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
70+
'matplotlib': ('https://matplotlib.org/stable', None),
71+
'shapely': ('https://shapely.readthedocs.io/en/stable', None),
72+
}
73+
74+
# Number of seconds for a cell to execute before timeout (default=30)
75+
nbsphinx_timeout = 60

‎docs/source/documentation.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. currentmodule:: twoaxistracking
2+
3+
4+
Code documentation
5+
==================
6+
7+
.. autosummary::
8+
:toctree: generated/
9+
10+
shaded_fraction
11+
generate_field_layout

0 commit comments

Comments
 (0)