diff --git a/.github/workflows/docs_pages.yml b/.github/workflows/docs_pages.yml new file mode 100644 index 0000000..cbfc15c --- /dev/null +++ b/.github/workflows/docs_pages.yml @@ -0,0 +1,45 @@ +name: BiRD-documentation + +on: + push: + branches: [ sphinx ] + paths: + - 'docs/**' + - '.github/workflows/docs_pages.yml' + +jobs: + + build_docs: + runs-on: ubuntu-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.10 + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install sphinx sphinx_rtd_theme sphinx-autoapi + + - name: Build documentation + run: | + cd docs + make html + + - name: deploy + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html + force_orphan: true + full_commit_message: ${{ github.event.head_commit.message }} + + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..f6d7249 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,29 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +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 + rm -rf _build + rm -rf source/_autosummary + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +github: html + -git branch -D gh-pages + -git push origin --delete gh-pages + ghp-import -n -b gh-pages -m "Update documentation" ./_build/html + git checkout gh-pages + git push --set-upstream origin gh-pages + git checkout ${BRANCH} diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..7843185 --- /dev/null +++ b/docs/make.bat @@ -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 + +if "%1" == "" goto help + +%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.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000..68fb29a --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,31 @@ +{% extends "!layout.html" %} + +{% block menu %} + {{ super() }} +

+ Indices +

+ + + {% if menu_links %} +

+ External links +

+ + {% endif %} +{% endblock %} + +{% block htmltitle %} + {% if title == '' or title == 'Home' %} + {{ docstitle|e }} + {% else %} + {{ title|striptags|e }}{{ titlesuffix }} + {% endif %} +{% endblock %} diff --git a/docs/source/_templates/notused_packages.rst_t b/docs/source/_templates/notused_packages.rst_t new file mode 100644 index 0000000..bc8412c --- /dev/null +++ b/docs/source/_templates/notused_packages.rst_t @@ -0,0 +1,52 @@ +{%- macro automodule(modname, options) -%} +.. automodule:: {{ modname }} +{%- for option in options %} + :{{ option }}: +{%- endfor %} +{%- endmacro %} + +{%- macro toctree(docnames) -%} +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} +{%- endmacro %} + +{%- if is_namespace %} +{{- [pkgname, "namespace"] | join(" ") | e | heading }} +{% else %} +{{- [pkgname, "package"] | join(" ") | e | heading }} +{% endif %} + +{%- if is_namespace %} +.. py:module:: {{ pkgname }} +{% endif %} + +{%- if modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} + +{%- if subpackages %} +Subpackages +----------- + +{{ toctree(subpackages) }} +{% endif %} + +{%- if submodules %} +Submodules +---------- +{% if separatemodules %} +{{ toctree(submodules) }} +{% else %} +{%- for submodule in submodules %} +{% if show_headings %} +{{- [submodule, "module"] | join(" ") | e | heading(2) }} +{% endif %} +{{ automodule(submodule, automodule_options) }} +{% endfor %} +{%- endif %} +{%- endif %} + +# https://github.com/sphinx-doc/sphinx/blob/master/sphinx/templates/apidoc diff --git a/docs/source/acknowledgments.rst b/docs/source/acknowledgments.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/acknowledgments.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..d6fd22d --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,88 @@ +# Configuration file for the Sphinx documentation builder. +import os +import sys +# Need this so sphinx can find lumache.py. Change is .py files are elsewhere than root. +sys.path.insert(0, os.path.abspath('../..')) +sys.path.insert(0, os.path.abspath('../../bird')) + +here = os.path.abspath(os.path.dirname(__file__)) + +with open(os.path.join(here, '..', '..', "bird", "version.py"), encoding="utf-8") as f: + version = f.read() +version = version.split("=")[-1].strip().strip('"').strip("'") + +# -- Project information + +project = "Bio Reactor Design (BiRD)" +copyright = '2024' +author = 'NREL' + +release = version +version = version + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +# 'autoapi.extension', +# 'sphinxcontrib.apidoc', +] + +#autoapi_type = 'python' +#autoapi_dirs = ['../../bird'] + +#apidoc_module_dir = '../../src' +#apidoc_output_dir = '.' +#apidoc_excluded_paths = ['tests'] +#apidoc_separate_modules = True + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' + +html_context = { + "display_github": True, # Integrate GitHub + "github_repo": "NREL/BioReactorDesign", # Repo name + "github_version": "main", # Version + "conf_py_path": "docs/source/", # Path in the checkout to the docs root +} + +# -- Options for HTML output ------------------------------------------------- + +html_short_title = "bird-doc" +html_show_sourcelink = False +html_show_sphinx = True +html_show_copyright = True + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +repository_url = f"https://github.com/NREL/BioReactorDesign" +html_context = { + "menu_links": [ + ( + ' Source Code', + repository_url, + ), + ( + ' License', + f"{repository_url}/blob/main/LICENSE", + ), + ], +} diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/contribute.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..f0b8145 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +Bio Reactor Design (BiRD) +=================================== + +`BiRD` is ... + +.. note:: + + This project is under active development. + + +.. toctree:: + :hidden: + + quickstart + meshing + preprocess + postprocess + contribute + references + acknowledgments diff --git a/docs/source/meshing.rst b/docs/source/meshing.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/meshing.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/postprocess.rst b/docs/source/postprocess.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/postprocess.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/preprocess.rst b/docs/source/preprocess.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/preprocess.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/references.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird +