-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from dc2917/add_docs
Added basic sphinx documentation
- Loading branch information
Showing
13 changed files
with
321 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
name: "Build documentation" | ||
on: | ||
pull_request: | ||
branches: | ||
- main | ||
push: | ||
branches: | ||
- main | ||
workflow_dispatch: | ||
jobs: | ||
build: | ||
timeout-minutes: 5 | ||
runs-on: ubuntu-latest | ||
permissions: | ||
contents: write | ||
steps: | ||
- uses: actions/checkout@v4 | ||
- uses: actions/setup-python@v5 | ||
with: | ||
python-version: "3.12" | ||
cache: "pip" | ||
cache-dependency-path: "requirements-dev.txt" | ||
- name: Gather dependencies | ||
run: | | ||
pip install -U pip | ||
pip install -r requirements-dev.txt | ||
- name: Build HTML | ||
run: sphinx-build -b html docs/source docs/build/html | ||
- name: Upload artifacts | ||
uses: actions/upload-artifact@v4 | ||
with: | ||
name: html-docs | ||
path: docs/build/html/ | ||
- name: Deploy | ||
uses: peaceiris/actions-gh-pages@v3 | ||
if: github.ref == 'refs/heads/main' | ||
with: | ||
github_token: ${{ secrets.GITHUB_TOKEN }} | ||
publish_dir: docs/build/html |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = source | ||
BUILDDIR = build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=source | ||
set BUILDDIR=build | ||
|
||
%SPHINXBUILD% >NUL 2>NUL | ||
if errorlevel 9009 ( | ||
echo. | ||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx | ||
echo.installed, then set the SPHINXBUILD environment variable to point | ||
echo.to the full path of the 'sphinx-build' executable. Alternatively you | ||
echo.may add the Sphinx directory to PATH. | ||
echo. | ||
echo.If you don't have Sphinx installed, grab it from | ||
echo.https://www.sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
if "%1" == "" goto help | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
API Reference | ||
============= | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
|
||
fargonaut | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
"""Configuration file for the Sphinx documentation builder.""" | ||
|
||
import os | ||
import sys | ||
|
||
sys.path.insert(0, os.path.abspath("../..")) | ||
|
||
|
||
# -- Project information ----------------------------------------------------- | ||
|
||
project = "Fargonaut" | ||
copyright = "2024, Dan Cummins" | ||
author = "Dan Cummins" | ||
|
||
|
||
# -- General configuration --------------------------------------------------- | ||
|
||
extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_rtd_theme"] | ||
|
||
templates_path = ["_templates"] | ||
exclude_patterns = [] | ||
|
||
|
||
# -- Options for HTML output ------------------------------------------------- | ||
|
||
html_theme = "sphinx_rtd_theme" | ||
html_static_path = ["_static"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
fargonaut.fields package | ||
======================== | ||
|
||
Submodules | ||
---------- | ||
|
||
fargonaut.fields.density module | ||
------------------------------- | ||
|
||
.. automodule:: fargonaut.fields.density | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
fargonaut.fields.energy module | ||
------------------------------ | ||
|
||
.. automodule:: fargonaut.fields.energy | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
fargonaut.fields.magnetic\_field module | ||
--------------------------------------- | ||
|
||
.. automodule:: fargonaut.fields.magnetic_field | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
fargonaut.fields.velocity module | ||
-------------------------------- | ||
|
||
.. automodule:: fargonaut.fields.velocity | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
Module contents | ||
--------------- | ||
|
||
.. automodule:: fargonaut.fields | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
fargonaut package | ||
================= | ||
|
||
Subpackages | ||
----------- | ||
|
||
.. toctree:: | ||
:maxdepth: 4 | ||
|
||
fargonaut.fields | ||
|
||
Submodules | ||
---------- | ||
|
||
fargonaut.field module | ||
---------------------- | ||
|
||
.. automodule:: fargonaut.field | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
fargonaut.output module | ||
----------------------- | ||
|
||
.. automodule:: fargonaut.output | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: | ||
|
||
Module contents | ||
--------------- | ||
|
||
.. automodule:: fargonaut | ||
:members: | ||
:undoc-members: | ||
:show-inheritance: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,14 @@ | ||
Fargonaut documentation | ||
======================= | ||
|
||
Fargonaut is an object-oriented toolkit for post-processing and visualising outputs of FARGO3D_, written in Python. | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
:caption: Contents: | ||
|
||
User Documentation <user_docs> | ||
API Reference <api_ref> | ||
|
||
|
||
.. _fargo3d: https://github.com/FARGO3D/fargo3d |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
User Documentation | ||
================== | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
|
||
user_docs/installation | ||
user_docs/basic_usage | ||
user_docs/contrib_guide |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
Basic Usage | ||
=========== | ||
|
||
Locate the directory containing the FARGO3D output you want to open. For demonstrative purposes, we will use "/path/to/fargo3d/outputs", and use the "fargo" output, created when running the example "fargo" setup. | ||
|
||
Open the Python interpreter:: | ||
|
||
$ python | ||
|
||
Import the top-level ``Output`` class:: | ||
|
||
>>> from fargonaut.output import Output | ||
|
||
Use this class to create an object for handling your output:: | ||
|
||
>>> output = Output("/path/to/fargo3d/outputs/fargo") | ||
|
||
Using the ``Output`` class:: | ||
|
||
>>> help(output) | ||
|
||
Retrieve variables defined in the variables.par file using the ``get_var`` method, e.g.:: | ||
|
||
>>> output.get_var("FRAME") | ||
'G' | ||
|
||
Some commonly used variables are stored as properties, in particular those related to the grid, e.g.:: | ||
|
||
>>> output.ny | ||
128 | ||
>>> output.nghy | ||
3 | ||
>>> len(output.ydomain) | ||
135 | ||
>>> output.xdomain | ||
array([-3.14159265, -3.12523019, -3.10886773, ..., 0, ... 3.14159265]) | ||
|
||
Use the ``get_field`` method to retrieve a field at a given output time. The names of the fields are those of the corresponding output files, e.g. to retrieve the gas density:: | ||
|
||
>>> gasdens50 = output.get_field("gasdens", 50) | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
Contributing Guidelines | ||
======================= | ||
|
||
Install the development requirements:: | ||
|
||
$ pip install -r requirements-dev.txt | ||
|
||
Install the pre-commit hooks:: | ||
|
||
$ pre-commit install | ||
|
||
Run the tests:: | ||
|
||
$ python -m unittest discover tests | ||
|
||
Check test coverage:: | ||
|
||
$ coverage run --omit=tests/* -m unittest discover tests | ||
$ coverage report -m | ||
|
||
Build the documentation:: | ||
|
||
$ cd docs | ||
$ make html |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
Installation | ||
============ | ||
|
||
The only requirements for installing Fargonaut are Git and Python. | ||
|
||
First, clone the repository:: | ||
|
||
$ git clone https://github.com/dc2917/Fargonaut | ||
|
||
Create a virtual environment to keep the Python packages separate from system packages and other local environments:: | ||
|
||
$ python -m venv .venv | ||
|
||
Activate the environment:: | ||
|
||
$ source .venv/bin/activate | ||
|
||
Install the dependencies:: | ||
|
||
$ pip install -r requirements.txt |