From 833347ecb0a14c6594892c1685262c99aeb11f44 Mon Sep 17 00:00:00 2001 From: Arnau Quera-Bofarull Date: Fri, 12 May 2023 16:37:55 +0100 Subject: [PATCH] new docs --- .github/workflows/ci.yml | 15 - .github/workflows/docs.yml | 41 ++ docs/_static/logo_small.svg | 909 +++++++++++++++++++++++++ docs/_static/mathjax.js | 16 + docs/_templates/autosummary/module.rst | 44 -- docs/api.rst | 12 - docs/api/infer.md | 3 + docs/birds.models.rst | 29 - docs/birds.rst | 45 -- docs/conf.py | 152 ----- docs/index.md | 1 + docs/index.rst | 22 - docs/modules.rst | 7 - docs/requirements.txt | 10 +- mkdocs.yml | 60 +- test/test_infer.py | 2 +- 16 files changed, 1034 insertions(+), 334 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/_static/logo_small.svg create mode 100644 docs/_static/mathjax.js delete mode 100644 docs/_templates/autosummary/module.rst delete mode 100644 docs/api.rst create mode 100644 docs/api/infer.md delete mode 100644 docs/birds.models.rst delete mode 100644 docs/birds.rst delete mode 100644 docs/conf.py create mode 100644 docs/index.md delete mode 100644 docs/index.rst delete mode 100644 docs/modules.rst diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 79e970f..86ecb10 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -41,18 +41,3 @@ jobs: with: token: ${{secrets.CODECOV_TOKEN}} verbose: true - - - name: Install docs dependencies - run: | - pip install sphinx furo - - name: Sphinx build - run: | - sphinx-build docs _build - - name: Deploy - uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} - with: - publish_branch: gh-pages - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: _build/ - force_orphan: true diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..22bd433 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,41 @@ +name: Build docs + +on: + push: + branches: + - main + +jobs: + build: + strategy: + matrix: + python-version: [ 3.9 ] + os: [ ubuntu-latest ] + runs-on: ${{ matrix.os }} + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install . + python -m pip install -r docs/requirements.txt + + - name: Build docs + run: | + mkdocs build + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: site + force_orphan: true diff --git a/docs/_static/logo_small.svg b/docs/_static/logo_small.svg new file mode 100644 index 0000000..9a81c26 --- /dev/null +++ b/docs/_static/logo_small.svg @@ -0,0 +1,909 @@ + + diff --git a/docs/_static/mathjax.js b/docs/_static/mathjax.js new file mode 100644 index 0000000..080801e --- /dev/null +++ b/docs/_static/mathjax.js @@ -0,0 +1,16 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.typesetPromise() +}) diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst deleted file mode 100644 index c0c8084..0000000 --- a/docs/_templates/autosummary/module.rst +++ /dev/null @@ -1,44 +0,0 @@ -{{ fullname | escape | underline}} - -.. automodule:: {{ fullname }} - - {% block modules %} - {% if modules %} - Submodules - ---------- - .. autosummary:: - :toctree: - :recursive: - {% for item in modules %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block functions %} - {% if functions %} - Functions - --------- - .. autosummary:: - :nosignatures: - {% for item in functions %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block classes %} - {% if classes %} - Classes - ------- - .. autosummary:: - :nosignatures: - {% for item in classes %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - Descriptions - ------------ - diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 89716ca..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,12 +0,0 @@ -API -=== - -.. module:: birds - -.. autosummary:: - :toctree: api - - birds.models - birds.forecast - birds.regularisation - diff --git a/docs/api/infer.md b/docs/api/infer.md new file mode 100644 index 0000000..54d95ca --- /dev/null +++ b/docs/api/infer.md @@ -0,0 +1,3 @@ +# Infer + +:::birds.infer diff --git a/docs/birds.models.rst b/docs/birds.models.rst deleted file mode 100644 index a87f4db..0000000 --- a/docs/birds.models.rst +++ /dev/null @@ -1,29 +0,0 @@ -birds.models package -==================== - -Submodules ----------- - -birds.models.coin\_flipping module ----------------------------------- - -.. automodule:: birds.models.coin_flipping - :members: - :undoc-members: - :show-inheritance: - -birds.models.random\_walk module --------------------------------- - -.. automodule:: birds.models.random_walk - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: birds.models - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/birds.rst b/docs/birds.rst deleted file mode 100644 index e24ca05..0000000 --- a/docs/birds.rst +++ /dev/null @@ -1,45 +0,0 @@ -birds package -============= - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - birds.models - -Submodules ----------- - -birds.forecast module ---------------------- - -.. automodule:: birds.forecast - :members: - :undoc-members: - :show-inheritance: - -birds.infer module ------------------- - -.. automodule:: birds.infer - :members: - :undoc-members: - :show-inheritance: - -birds.regularisation module ---------------------------- - -.. automodule:: birds.regularisation - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: birds - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 7af3674..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,152 +0,0 @@ -# Configuration file for the Sphinx documentation builder - -import glob -import inspect -import importlib -import re -import subprocess -import birds - -## Project - -package = "birds" -project = "birds" -version = birds.__version__ -copyright = '2023, Arnau Quera-Bofarull, Joel Dyer, Ayush Chopra' -repository = "https://github.com/arnauqb/birds" -author = 'Arnau Quera-Bofarull, Joel Dyer, Ayush Chopra' -release = '0.1' - -## Extensions - -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.githubpages", - "sphinx.ext.intersphinx", - "sphinx.ext.linkcode", - "sphinx.ext.napoleon", -] - -autodoc_default_options = { - "members": True, - "member-order": "bysource", -} -autodoc_inherit_docstrings = False -autodoc_typehints = "description" -autodoc_typehints_description_target = "documented" -autodoc_typehints_format = "short" - -autosummary_ignore_module_all = False - -intersphinx_mapping = { - "numpy": ("https://numpy.org/doc/stable", None), - "python": ("https://docs.python.org/3", None), - "torch": ("https://pytorch.org/docs/stable", None), -} - - -def linkcode_resolve(domain: str, info: dict) -> str: - module = info.get("module", "") - fullname = info.get("fullname", "") - - if not module or not fullname: - return None - - objct = importlib.import_module(module) - for name in fullname.split("."): - objct = getattr(objct, name) - - try: - file = inspect.getsourcefile(objct) - file = file[file.rindex(package) :] - - lines, start = inspect.getsourcelines(objct) - end = start + len(lines) - 1 - except Exception as e: - return None - else: - return f"{repository}/blob/{release}/{file}#L{start}-L{end}" - - -napoleon_custom_sections = [ - ("Shapes", "params_style"), - "Wikipedia", -] - -## Settings - -add_function_parentheses = False -default_role = "literal" -exclude_patterns = ["_templates"] -html_copy_source = False -html_css_files = [ - "custom.css", - "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css", -] -html_favicon = "_static/logo.jpg" -html_logo = "_static/logo.jpg" -html_show_sourcelink = False -html_sourcelink_suffix = "" -html_static_path = ["_static"] -html_theme = "furo" -html_theme_options = { - "footer_icons": [ - { - "name": "GitHub", - "url": repository, - "html": '', - "class": "", - }, - ], - "light_css_variables": { - "color-api-keyword": "#007020", - "color-api-name": "#0e84b5", - "color-api-pre-name": "#0e84b5", - }, - "dark_css_variables": { - "color-api-keyword": "#66d9ef", - "color-api-name": "#a6e22e", - "color-api-pre-name": "#a6e22e", - }, - "sidebar_hide_name": True, -} -html_title = f"{project} {version}" -pygments_style = "sphinx" -pygments_dark_style = "monokai" -rst_prolog = """ -.. role:: py(code) - :class: highlight - :language: python -""" -templates_path = ["_templates"] - -## Edit HTML - - -def edit_html(app, exception): - if exception: - raise exception - - for file in glob.glob(f"{app.outdir}/**/*.html", recursive=True): - with open(file, "r") as f: - text = f.read() - - text = text.replace( - '@pradyunsg\'s', "" - ) - text = text.replace( - '[source]', '' - ) - text = re.sub( - r'()()', - r"\2\1", - text, - ) - - with open(file, "w") as f: - f.write(text) - - -def setup(app): - app.connect("build-finished", edit_html) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..18e694c --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +# BIRDS documentation diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 214e9b7..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. birds documentation master file, created by - sphinx-quickstart on Wed May 10 19:57:14 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to birds's documentation! -================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - modules - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/modules.rst b/docs/modules.rst deleted file mode 100644 index 391576a..0000000 --- a/docs/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -birds -===== - -.. toctree:: - :maxdepth: 4 - - birds diff --git a/docs/requirements.txt b/docs/requirements.txt index 29843eb..4b3631e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,7 @@ -docutils==0.19 -furo==2023.3.27 -sphinx==6.1.3 +mkdocs==1.4.3 +mkdocs-material==9.1.12 +mkdocstrings==0.21.2 +mknotebooks==0.7.1 +mkdocstrings-python==0.10.1 + + diff --git a/mkdocs.yml b/mkdocs.yml index be35738..267a2c0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,15 +1,67 @@ site_name: BIRDS +site_description: Documentation for the BIRDS library. site_url: https://arnauqb.github.io/birds -nav: - - Home: index.md -theme: readthedocs +site_author: Arnau Quera-Bofarull + +repo_url: https://github.com/arnauqb/birds + +extra_javascript: + - _static/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + +theme: + name: "material" + features: + - navigation.sections # Sections are included in the navigation on the left. + - toc.integrate # Table of contents is integrated on the left; does not appear separately on the right. + - header.autohide # header disappears as you scroll + palette: + # Light mode / dark mode + # We deliberately don't automatically use `media` to check a user's preferences. We default to light mode as + # (a) it looks more professional, and (b) is more obvious about the fact that it offers a (dark mode) toggle. + - scheme: default + primary: white + accent: amber + toggle: + icon: material/weather-night + name: Switch to dark mode + - scheme: slate + primary: black + accent: amber + toggle: + icon: material/weather-sunny + name: Switch to light mode + icon: + repo: fontawesome/brands/github # GitHub logo in top right + logo: fontawesome/solid/crow # birds icon + #logo: "material/math-integral-box" + favicon: "_static/logo.jpg" + #custom_dir: "docs/_overrides" # Overriding part of the HTML + markdown_extensions: - pymdownx.arithmatex: generic: true + - pymdownx.superfences # Seems to enable syntax highlighting when used with the Material theme. + - pymdownx.details # Allowing hidden expandable regions denoted by ??? + - pymdownx.snippets: # Include one Markdown file into another + base_path: docs + - admonition + - toc: + permalink: "ยค" # Adds a clickable permalink to each section heading + toc_depth: 4 # Prevents h5, h6 (i.e. methods) from showing up in the TOC. + extra_javascript: - javascripts/mathjax.js - https://polyfill.io/v3/polyfill.min.js?features=es6 - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js -plugins: + +plugins - search - mkdocstrings + - mknotebooks + +nav: + - index.md + - API: + - api/infer.md diff --git a/test/test_infer.py b/test/test_infer.py index 43fc591..add0c06 100644 --- a/test/test_infer.py +++ b/test/test_infer.py @@ -45,7 +45,7 @@ def test_random_walk(self): optimizer=optimizer, diff_mode=diff_mode, ) - _, best_model_state_dict = calib.run(1000) + _, best_model_state_dict = calib.run(1000) posterior_estimator.load_state_dict(best_model_state_dict) assert np.isclose(posterior_estimator.mu.item(), true_p, rtol=0.25) assert posterior_estimator.sigma.item() < 1e-2