Skip to content

Commit 0b31080

Browse files
pgleesonpgleeson
authored
Merge pull request #43 from Onoyiza/add_sphinx_documentation
Test sphinx documentation
2 parents 78735ed + 3ed1f91 commit 0b31080

24 files changed

+904
-1
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ instance/
8080

8181
# Sphinx documentation
8282
docs/_build/
83+
docs/sphinx/source/api/_autosummary
8384

8485
# PyBuilder
8586
.pybuilder/

‎docs/generate.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import shutil
2+
import os
3+
4+
shutil.copy("../README.md", "sphinx/source/api/Introduction.md")
5+
6+
for file_ in os.listdir("../examples"):
7+
if ("document" in file_) or ("README" in file_):
8+
shutil.copy(
9+
"../examples/%s" % file_, os.path.join("sphinx/source/api/examples", file_)
10+
)

‎docs/sphinx/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/sphinx/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/sphinx/source/_static/pydata-custom.css

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/*Tweaks to the Pydata default CSS */
2+
3+
/*No yellow background highlight when targeted by summary tables */
4+
/*dt:target { background-color: #f8f8f8; border: 1px solid black, }*/
5+
dt:target { background: transparent;}
6+
/*More space between H1s and signatures in API reference*/
7+
h1 { margin-bottom: 40px; }
8+
9+
/*No line underneath summary table headings (clashes with line above first member)*/
10+
p.rubric { border-bottom: 0px; }

‎docs/sphinx/source/_static/rtd-custom.css

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
/* Override nav bar color */
2+
/*.wy-side-nav-search {
3+
background-color: #fbfbb6;
4+
}
5+
.wy-side-nav-search > a {
6+
color: #b2355c
7+
}*/
8+
9+
/* Override text bar color */
10+
/*.caption-text {
11+
color: #b2355c;
12+
}*/
13+
14+
/* Override code signature colour */
15+
/*.rst-content dl:not(.docutils) dt {
16+
background: #fbfbb6;
17+
color: #b2355c;
18+
border-top: solid 3px #b2355c;
19+
}*/
20+
21+
/* Override hyperlink colour */
22+
/* a {
23+
color: #b2355c;
24+
}*/
25+
26+
/* Make content width wider*/
27+
.wy-nav-content {
28+
max-width: 75% !important;
29+
}
30+
31+
/* Word-wrap tables */
32+
.wy-table-responsive table td,
33+
.wy-table-responsive table th {
34+
white-space: normal;
35+
}

‎docs/sphinx/source/_templates/custom-class-template.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
:members:
7+
:show-inheritance:
8+
:special-members: __call__, __add__, __mul__
9+
10+
{% block methods %}
11+
{% if methods %}
12+
.. rubric:: {{ _('Methods') }}
13+
14+
.. autosummary::
15+
{% for item in methods %}
16+
{%- if not item.startswith('_') %}
17+
{%- if item not in inherited_members %}
18+
~{{ name }}.{{ item }}
19+
{%- endif -%}
20+
{%- endif -%}
21+
{%- endfor %}
22+
{% endif %}
23+
{% endblock %}

‎docs/sphinx/source/_templates/custom-module-template.rst

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. automodule:: {{ fullname }}
4+
5+
{% block attributes %}
6+
{% if attributes %}
7+
.. rubric:: Module attributes
8+
9+
.. autosummary::
10+
:toctree:
11+
{% for item in attributes %}
12+
{{ item }}
13+
{%- endfor %}
14+
{% endif %}
15+
{% endblock %}
16+
17+
{% block functions %}
18+
19+
{% if functions %}
20+
.. rubric:: {{ _('Functions') }}
21+
22+
.. autosummary::
23+
:toctree:
24+
{% for item in functions %}
25+
{%- if not item.startswith('_') %}
26+
{{ item }}
27+
{% endif %}
28+
{%- endfor %}
29+
{% endif %}
30+
{% endblock %}
31+
32+
{% block classes %}
33+
{% if classes %}
34+
.. rubric:: {{ _('Classes') }}
35+
36+
.. autosummary::
37+
:toctree:
38+
:template: custom-class-template.rst
39+
{% for item in classes %}
40+
{{ item }}
41+
{%- endfor %}
42+
{% endif %}
43+
{% endblock %}
44+
45+
{% block exceptions %}
46+
{% if exceptions %}
47+
.. rubric:: {{ _('Exceptions') }}
48+
49+
.. autosummary::
50+
:toctree:
51+
{% for item in exceptions %}
52+
{{ item }}
53+
{%- endfor %}
54+
{% endif %}
55+
{% endblock %}
56+
57+
{% block modules %}
58+
{% if modules %}
59+
.. autosummary::
60+
:toctree:
61+
:template: custom-module-template.rst
62+
:recursive:
63+
{% for item in modules %}
64+
{{ item }}
65+
{%- endfor %}
66+
{% endif %}
67+
{% endblock %}

‎docs/sphinx/source/api/Installation.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Installation
2+
3+
## Requirements
4+
5+
Python >=3.7 is required. Support on Python 3.11 is limited.
6+
7+
## Installation using pip
8+
9+
Use pip to install the latest version of Modelspec (plus dependencies) from [PyPI](https://pypi.org/project/modelspec):
10+
```
11+
pip install modelspec
12+
```
13+
14+
## Installation from source
15+
To install the modelspec package from [source](https://github.com/ModECI/modelspec) and run it locally:
16+
17+
### 1) Create a virtual environment (e.g. called `modelspec-env`)
18+
```
19+
pip install virtualenv
20+
virtualenv modelspec-env
21+
```
22+
23+
### 2) Activate the virtual environment
24+
```
25+
source modelspec-env/bin/activate
26+
```
27+
28+
### 3) Clone this repository
29+
```
30+
git clone https://github.com/ModECI/modelspec.git
31+
```
32+
33+
### 4) Change to the directory
34+
```
35+
cd modelspec
36+
```
37+
38+
### 5) Install the package
39+
```
40+
pip install .
41+
```
42+
43+
Alternatively, to install modelspec plus optional dependencies:
44+
45+
```
46+
pip install .[all]
47+
```
48+
49+
## Generating modelspec documentation offline
50+
51+
Here is a walkthrough on how to generate the modelspec documentation offline
52+
53+
### Requirements
54+
55+
The documentation is generated using [Sphinx](https://www.sphinx-doc.org). Make is also required. For **Windows** installation of Make, see [here](https://stackoverflow.com/questions/32127524/how-to-install-and-use-make-in-windows). For **Mac** installation of Make, see [here](https://formulae.brew.sh/formula/make)
56+
57+
58+
59+
#### 1) Create a virtual environment with python
60+
```
61+
# install virtual environment
62+
63+
pip install virtualenv
64+
65+
# create & activate a virtual environment for your current or preferred python version
66+
67+
python -m virtualenv modelspec-env
68+
modelspec-env\Scripts\activate
69+
```
70+
71+
#### 2) Clone modelspec repository from GitHub into your local machine
72+
```
73+
git clone https://github.com/ModECI/modelspec.git
74+
```
75+
76+
#### 3) Change into the modelspec directory
77+
```
78+
cd modelspec
79+
```
80+
81+
#### 4) Install all modelspec package into the virtual environment
82+
```
83+
pip install .[all]
84+
```
85+
86+
#### 5) Change directory into sphinx folder
87+
```
88+
# for windows
89+
cd docs\sphinx
90+
91+
# for Mac/Linux
92+
cd docs/sphinx
93+
```
94+
95+
#### 6) Create offline documentation in sphinx folder
96+
```
97+
# To allow a fresh start when making the documentation
98+
make clean
99+
100+
# To make the documentation
101+
make html
102+
```
103+
104+
#### 7) Change directory into html folder and run the documentation offline
105+
```
106+
# for Windows go into build\html folder and double click on the index.html file, or:
107+
108+
cd build\html
109+
index.html
110+
111+
# for Mac, go into build/html folder and double click on the index.html file or:
112+
cd build/html
113+
open index.html
114+
```
115+
116+
The documentation will open up in your browser automatically or right click on the file and open in any browser of your choice.

‎docs/sphinx/source/api/Introduction.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Modelspec
2+
3+
4+
[![Continuous builds](https://github.com/ModECI/modelspec/actions/workflows/ci.yml/badge.svg)](https://github.com/ModECI/modelspec/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/modelspec)](https://pypi.org/project/modelspec/)
5+
6+
7+
Functionality for specifying the structure of models & enabling automatic serialization to them (e.g. in JSON and YAML format).
8+
9+
This package is being used by [NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) & [MDF](https://github.com/ModECI/MDF).
10+
11+
For an example of the use of this package see [here](examples/README.md).

0 commit comments

Comments
 (0)