From af5fc4edc5bf5fd1d75b6617251edce5e68635c9 Mon Sep 17 00:00:00 2001 From: John Vouvakis Manousakis Date: Fri, 13 Sep 2024 04:30:49 -0700 Subject: [PATCH] Set up Sphinx. - Add GitHub workflow. - Simplify doc build workflow and add requirements. - Remove currently unused extensions in `conf.py`. - Add a few documentation pages. --- .github/workflows/build_docs.yaml | 26 +++++ .github/{ => workflows}/format_and_lint.yaml | 0 .gitignore | 3 + doc/Makefile | 20 ++++ doc/make.bat | 35 +++++++ doc/source/_static/css/custom.css | 33 +++++++ .../_templates/custom-class-template.rst | 32 +++++++ .../_templates/custom-module-template.rst | 63 ++++++++++++ doc/source/about/about.rst | 11 +++ doc/source/conf.py | 95 +++++++++++++++++++ doc/source/index.rst | 18 ++++ doc/source/references.bib | 0 doc/source/release_notes/index.rst | 16 ++++ doc/source/release_notes/v1.0.rst | 10 ++ 14 files changed, 362 insertions(+) create mode 100644 .github/workflows/build_docs.yaml rename .github/{ => workflows}/format_and_lint.yaml (100%) create mode 100644 doc/Makefile create mode 100644 doc/make.bat create mode 100644 doc/source/_static/css/custom.css create mode 100644 doc/source/_templates/custom-class-template.rst create mode 100644 doc/source/_templates/custom-module-template.rst create mode 100644 doc/source/about/about.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 doc/source/references.bib create mode 100644 doc/source/release_notes/index.rst create mode 100644 doc/source/release_notes/v1.0.rst diff --git a/.github/workflows/build_docs.yaml b/.github/workflows/build_docs.yaml new file mode 100644 index 0000000..60122e8 --- /dev/null +++ b/.github/workflows/build_docs.yaml @@ -0,0 +1,26 @@ +name: Build and deploy documentation +on: + push: + branches: + - docs +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v3 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y pandoc + python -m pip install sphinx sphinx_design sphinx-rtd-theme sphinxcontrib-bibtex numpydoc + - name: Build docs + run: cd doc && make html + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./doc/build/html diff --git a/.github/format_and_lint.yaml b/.github/workflows/format_and_lint.yaml similarity index 100% rename from .github/format_and_lint.yaml rename to .github/workflows/format_and_lint.yaml diff --git a/.gitignore b/.gitignore index c9efffd..5c11afc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ /data_sources/HAZUS_MH_4.2_HU/output/ /data_sources/HAZUS_MH_4.2_HU/session.dill +/doc/build/ +*.pyc +/.ropeproject/ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/doc/Makefile @@ -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) diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..dc1312a --- /dev/null +++ b/doc/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 + +%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 diff --git a/doc/source/_static/css/custom.css b/doc/source/_static/css/custom.css new file mode 100644 index 0000000..17f191d --- /dev/null +++ b/doc/source/_static/css/custom.css @@ -0,0 +1,33 @@ +wy-nav-content { + max-width: none; +} + + +.math { + text-align: left; +} + +.eqno { + float: right; +} + + +#div.wy-side-scroll{ +# background:#cb463f; +#} + +div.wy-menu.wy-menu-vertical > .caption { + color: #cb463f; +} + +# LIGHT BLUE background:#0099ff +# BLUE: background:#0B619C +# ADAM RED: background:#cb463f; + +span.caption.caption-text{ + color: #000000; +} + +td{ + white-space: normal !important; +} diff --git a/doc/source/_templates/custom-class-template.rst b/doc/source/_templates/custom-class-template.rst new file mode 100644 index 0000000..b29757c --- /dev/null +++ b/doc/source/_templates/custom-class-template.rst @@ -0,0 +1,32 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :inherited-members: + + {% block methods %} + .. automethod:: __init__ + + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/doc/source/_templates/custom-module-template.rst b/doc/source/_templates/custom-module-template.rst new file mode 100644 index 0000000..dc53556 --- /dev/null +++ b/doc/source/_templates/custom-module-template.rst @@ -0,0 +1,63 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + :members: + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :template: custom-class-template.rst + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :template: custom-module-template.rst + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/doc/source/about/about.rst b/doc/source/about/about.rst new file mode 100644 index 0000000..8d06eda --- /dev/null +++ b/doc/source/about/about.rst @@ -0,0 +1,11 @@ +.. _about: + +.. admonition:: Coming soon + + This section is under construction. + +******* + About +******* + +About the damage and loss model library. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..418c404 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,95 @@ +"""Damage and Loss Model Library Sphinx configuration.""" + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +from datetime import datetime + +# -- Project information ----------------------------------------------------- +project = 'Damage and Loss Model Library' +copyright = ( + f'{datetime.now().year}, Leland Stanford Junior ' + f'University and The Regents of the University of California' +) + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'numpydoc', + 'sphinx_design', + 'sphinxcontrib.bibtex', + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.doctest', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# 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'] + +html_css_files = ['css/custom.css'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# Extension configuration + +autosummary_generate = True # Turn on sphinx.ext.autosummary + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'numpy': ('http://docs.scipy.org/doc/numpy/', None), + 'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None), +} + +numpydoc_show_class_members = False # TODO(JVM): remove and extend docstrings + +nbsphinx_custom_formats = { + '.pct.py': ['jupytext.reads', {'fmt': 'py:percent'}], +} + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +html_theme_options = { + 'analytics_id': None, # TODO (AZ): Add analytics ID. + 'logo_only': True, + 'collapse_navigation': False, + 'prev_next_buttons_location': None, + 'navigation_depth': 2, + 'style_nav_header_background': '#F2F2F2', +} +html_show_sphinx = False # Removes "Built with Sphinx using a theme [...]" +html_show_sourcelink = ( + False # Remove 'view source code' from top of page (for html, not python) +) +numfig = True +bibtex_bibfiles = ['references.bib'] +bibtex_style = 'plain' diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..561aee9 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,18 @@ +:notoc: + +=============================== + Damage and Loss Model Library +=============================== + +.. warning:: + + Development Preview Only. + This documentation is intended for internal review and demonstration purposes. + It is not finalized or ready for public use. + +.. toctree:: + :caption: About + :maxdepth: 1 + + about/about.rst + release_notes/index.rst diff --git a/doc/source/references.bib b/doc/source/references.bib new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/release_notes/index.rst b/doc/source/release_notes/index.rst new file mode 100644 index 0000000..aade0af --- /dev/null +++ b/doc/source/release_notes/index.rst @@ -0,0 +1,16 @@ +.. _release_notes: + +************* +Release Notes +************* + +The following sections document the notable changes of each release. +The sequence of all changes is available in the `commit logs `_. + +Version 1 +----------- + +.. toctree:: + :maxdepth: 2 + + v1.0 diff --git a/doc/source/release_notes/v1.0.rst b/doc/source/release_notes/v1.0.rst new file mode 100644 index 0000000..7d988c2 --- /dev/null +++ b/doc/source/release_notes/v1.0.rst @@ -0,0 +1,10 @@ +.. _changes_v1_0: + +========================== +Version 1.0 (May 19, 2023) +========================== + +Initial Release. + +- FEMA P-58 2nd edition. +- Hazus Earthquake Model for Buildings.