From 733aafc719ded569b476bbbbd7a4418191b671ed Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 12 Jan 2024 22:03:25 +0100 Subject: [PATCH 1/4] DOC: update link to `pycompwa` website (#513) --- docs/index.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6d7364a3..780c1d53 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,13 +13,7 @@ :::{margin} -TensorWaves originates from [`pycompwa`](https://compwa.github.io), which did its -computations through a function tree that is similar to -[TensorFlow graphs](https://www.tensorflow.org/tensorboard/graphs) and -[SymPy expression trees](https://docs.sympy.org/latest/tutorial/manipulation.html). The -decision to use Python only has been further inspired by -[TensorFlowAnalysis](https://gitlab.cern.ch/poluekt/TensorFlowAnalysis), -[AmpliTF](https://github.com/apoluekt/AmpliTF) and [zfit](https://github.com/zfit/zfit). +TensorWaves originates from [`pycompwa`](https://github.com/ComPWA/pycompwa), which did its computations through a function tree that is similar to [TensorFlow graphs](https://www.tensorflow.org/tensorboard/graphs) and [SymPy expression trees](https://docs.sympy.org/latest/tutorial/manipulation.html). The decision to use Python only has been further inspired by [TensorFlowAnalysis](https://gitlab.cern.ch/poluekt/TensorFlowAnalysis), [AmpliTF](https://github.com/apoluekt/AmpliTF) and [zfit](https://github.com/zfit/zfit). ::: From d03d97c1764726f7a5e180e704d214903b278ebe Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Sat, 20 Jan 2024 13:10:04 +0100 Subject: [PATCH 2/4] DOC: update links to compwa.github.io (#514) --- CONTRIBUTING.md | 4 +--- docs/amplitude-analysis.ipynb | 2 +- docs/conf.py | 6 +++--- docs/index.md | 4 ++-- docs/install.md | 20 ++++++++++---------- src/tensorwaves/function/sympy/__init__.py | 2 +- 6 files changed, 18 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5a8a72b..4cfacdba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,4 @@ [![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/tensorwaves) [![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/tensorwaves) -This package is part of the [ComPWA Organization](https://github.com/ComPWA). For more -information about how to contribute to the packages, go to -[compwa-org.rtfd.io/en/stable/develop.html](https://compwa-org.rtfd.io/en/stable/develop.html)! +This package is part of the [ComPWA Organization](https://github.com/ComPWA). For more information about how to contribute to the packages, go to [compwa.github.io/develop](https://compwa.github.io/develop)! diff --git a/docs/amplitude-analysis.ipynb b/docs/amplitude-analysis.ipynb index bae91f98..bbbe9506 100644 --- a/docs/amplitude-analysis.ipynb +++ b/docs/amplitude-analysis.ipynb @@ -342,7 +342,7 @@ "source": [ "::::{margin}\n", ":::{tip}\n", - "{doc}`TR-018` explains some of the mechanisms behind the phase space generator as well as how to do {ref}`importance sampling`.\n", + "{doc}`TR-018` explains some of the mechanisms behind the phase space generator as well as how to do {ref}`importance sampling`.\n", ":::\n", "::::\n", "\n", diff --git a/docs/conf.py b/docs/conf.py index 58460b72..3f4380df 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -144,7 +144,7 @@ def get_tensorflow_url() -> str: "icon_links": [ { "name": "Common Partial Wave Analysis", - "url": "https://compwa-org.rtfd.io", + "url": "https://compwa.github.io", "icon": "_static/favicon.ico", "type": "local", }, @@ -201,7 +201,7 @@ def get_tensorflow_url() -> str: html_title = REPO_TITLE intersphinx_mapping = { "ampform": (f"https://ampform.readthedocs.io/en/{pin('ampform')}", None), - "compwa-org": ("https://compwa-org.readthedocs.io", None), + "compwa": ("https://compwa.github.io", None), "graphviz": ("https://graphviz.readthedocs.io/en/stable", None), "iminuit": ("https://iminuit.readthedocs.io/en/stable", None), "jax": ("https://jax.readthedocs.io/en/latest", None), @@ -237,7 +237,7 @@ def get_tensorflow_url() -> str: "run_interactive": f""" ```{{margin}} Run this notebook [on Binder]({BINDER_LINK}) or -{{ref}}`locally on Jupyter Lab ` to interactively +{{ref}}`locally on Jupyter Lab ` to interactively modify the parameters. ``` """, diff --git a/docs/index.md b/docs/index.md index 780c1d53..3e14106c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -74,7 +74,7 @@ API Continuous benchmarks Changelog Upcoming features -Help developing +Help developing ``` ```{toctree} @@ -85,5 +85,5 @@ hidden: QRules AmpForm PWA Pages -ComPWA project +ComPWA project ``` diff --git a/docs/install.md b/docs/install.md index e715aedb..9218d906 100644 --- a/docs/install.md +++ b/docs/install.md @@ -11,7 +11,7 @@ The fastest way of installing this package is through PyPI or Conda: :::{margin} TensorWaves can work with different computational backends. They are provided through -{ref}`optional dependencies `. +{ref}`optional dependencies `. [JAX](https://jax.readthedocs.io) is usually the fastest backend, so it's recommended to install that as in the install examples here. @@ -115,7 +115,7 @@ run into trouble. [create an NVIDIA account](https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html#download). 5. **[Recommended]** Install JAX with GPU binaries in your - {ref}`virtual environment ` following + {ref}`virtual environment ` following [these instructions](https://github.com/google/jax#pip-installation-gpu-cuda). ```shell @@ -160,13 +160,13 @@ python3 -m pip install "tensorwaves[jax,pwa] @ git+https://github.com/ComPWA/ten If you are working on {doc}`amplitude analysis `, we highly recommend using the more dynamic -{ref}`'editable installation' ` instead. This +{ref}`'editable installation' ` instead. This allows you to: -- exactly {ref}`pin all dependencies ` +- exactly {ref}`pin all dependencies ` to a specific version, so that your work is **reproducible**. - edit the source code of the framework and - {doc}`help improving it `. + {doc}`help improving it `. For this, you first need to get the source code with [Git](https://git-scm.com): @@ -196,11 +196,11 @@ This installs the project in a Conda environment following the definitions in 1. **[Recommended]** Create a virtual environment with [`venv`](https://docs.python.org/3/library/venv.html) (see - {ref}`here `). + {ref}`here `). 2. Install the project as an - {ref}`'editable installation' ` with - {ref}`additional packages ` for the + {ref}`'editable installation' ` with + {ref}`additional packages ` for the developer and all dependencies pinned through [constraints files](https://pip.pypa.io/en/stable/user_guide/#constraints-files): @@ -212,9 +212,9 @@ This installs the project in a Conda environment following the definitions in :::: -See {ref}`compwa-org:develop:Updating` for how to update the dependencies when new +See {ref}`compwa:develop:Updating` for how to update the dependencies when new commits come in. That's all! Have a look at {doc}`/usage` to try out the package. You can also have a -look at {doc}`compwa-org:develop` for tips on how to work with this 'editable' developer +look at {doc}`compwa:develop` for tips on how to work with this 'editable' developer setup! diff --git a/src/tensorwaves/function/sympy/__init__.py b/src/tensorwaves/function/sympy/__init__.py index 6b1a8c01..f351def2 100644 --- a/src/tensorwaves/function/sympy/__init__.py +++ b/src/tensorwaves/function/sympy/__init__.py @@ -42,7 +42,7 @@ def create_function( function faster and speeds up lambdification. max_complexity: See :ref:`usage/faster-lambdify:Specifying complexity` and - :doc:`compwa-org:report/002`. + :doc:`compwa:report/002`. Example: >>> import numpy as np From 4fe7b708fb34089d3d7340c51d54cd55da7f7bc7 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Sat, 20 Jan 2024 23:29:07 +0100 Subject: [PATCH 3/4] DOC: remove `.html` from page URLs (#515) * MAINT: remove redundant templates --- .cspell.json | 2 -- .readthedocs.yml | 2 +- docs/_templates/genindex.html | 55 ----------------------------------- docs/_templates/layout.html | 4 --- docs/_templates/module.rst_t | 12 -------- docs/_templates/package.rst_t | 49 ------------------------------- docs/_templates/toc.rst_t | 7 ----- tox.ini | 6 ++-- 8 files changed, 5 insertions(+), 132 deletions(-) delete mode 100644 docs/_templates/genindex.html delete mode 100644 docs/_templates/layout.html delete mode 100644 docs/_templates/module.rst_t delete mode 100644 docs/_templates/package.rst_t delete mode 100644 docs/_templates/toc.rst_t diff --git a/.cspell.json b/.cspell.json index 1514d3f6..8b686e06 100644 --- a/.cspell.json +++ b/.cspell.json @@ -20,7 +20,6 @@ "transisions" ], "ignorePaths": [ - "**/*.rst_t", "**/.cspell.json", ".constraints/*.txt", ".editorconfig", @@ -32,7 +31,6 @@ ".vscode/*", "CITATION.cff", "codecov.yml", - "docs/_templates/*", "docs/conf.py", "pyproject.toml", "tox.ini", diff --git a/.readthedocs.yml b/.readthedocs.yml index 2bda1f49..413a5495 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,7 +1,7 @@ version: 2 sphinx: - builder: html + builder: dirhtml configuration: docs/conf.py fail_on_warning: true diff --git a/docs/_templates/genindex.html b/docs/_templates/genindex.html deleted file mode 100644 index 21849ec3..00000000 --- a/docs/_templates/genindex.html +++ /dev/null @@ -1,55 +0,0 @@ -{% macro indexentries(firstname, links) %} {%- if links -%} - - {%- if links[0][0] %}{% endif -%} {{ firstname|e }} {%- if links[0][0] %}{% endif -%} - - -{%- for ismain, link in links[1:] -%} , -{% if ismain %}{% endif -%} [{{ loop.index }}] {%- if ismain %}{% endif -%} - -{%- endfor %} {%- else %} {{ firstname|e }} {%- endif %} {% endmacro %} {%- -extends "layout.html" %} {% set title = _('Index') %} {% block body %} - -

{{ _('Index') }}

- -
- {% for key, dummy in genindexentries -%} - {{ key }} - {% if not loop.last %}| {% endif %} {%- endfor %} -
- -{%- for key, entries in genindexentries %} -

{{ key }}

- - - {%- for entryname, (links, subitems, _) in entries %} -
  • - {{ indexentries(entryname, links) }} {%- if subitems %} -
      - {%- for subentryname, subentrylinks in subitems %} -
    • {{ indexentries(subentryname, subentrylinks) }}
      • - {%- endfor %} -
    - {%- endif -%} -
    • - {%- endfor %} - -
    -{% endfor %} {% endblock %} {% block sidebarrel %} {% if split_index %} -

    {{ _('Index') }}

    -

    - {% for key, dummy in genindexentries -%} - {{ key }} - {% if not loop.last %}| {% endif %} {%- endfor %} -

    - -

    - {{ _('Full index on one page') }} -

    -{% endif %} {{ super() }} {% endblock %} diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html deleted file mode 100644 index 25d65cd5..00000000 --- a/docs/_templates/layout.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "!layout.html" %} {% block menu %} {{ super() }} -Module Index (API) -General Index -{% endblock %} diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t deleted file mode 100644 index 6d477106..00000000 --- a/docs/_templates/module.rst_t +++ /dev/null @@ -1,12 +0,0 @@ -{%- if show_headings and not separate %} -{{ basename.split(".")[-1] | e | heading }} - -.. code-block:: python - - import {{ basename }} - -{% endif -%} -.. automodule:: {{ qualname }} -{%- for option in automodule_options %} - :{{ option }}: -{%- endfor %} diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t deleted file mode 100644 index cac2570e..00000000 --- a/docs/_templates/package.rst_t +++ /dev/null @@ -1,49 +0,0 @@ -{%- macro automodule(modname, options) -%} -.. automodule:: {{ modname }} -{%- for option in options %} - :{{ option }}: -{%- endfor %} -{%- endmacro %} - -{%- macro toctree(docnames) -%} -.. toctree:: -{% for docname in docnames %} - {{ docname }} -{%- endfor %} -{%- endmacro %} - -{{ pkgname.split(".")[-1] | e | heading }} - -.. code-block:: python - - import {{ pkgname }} - -{%- if modulefirst and not is_namespace %} -{{ automodule(pkgname, automodule_options) }} -{% endif %} - -{%- if not modulefirst and not is_namespace %} - -{{ automodule(pkgname, automodule_options) }} -{% endif %} - -{%- if submodules or subpackages %} -.. rubric:: Submodules and Subpackages -{% endif %} - -{%- if subpackages %} - -{{ toctree(subpackages) }} -{% endif %} -{%- if 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 %} diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t deleted file mode 100644 index cba06b1a..00000000 --- a/docs/_templates/toc.rst_t +++ /dev/null @@ -1,7 +0,0 @@ -{{ header | heading }} - -.. toctree:: - :maxdepth: {{ maxdepth }} -{% for docname in docnames %} - {{ docname }} -{%- endfor %} diff --git a/tox.ini b/tox.ini index 355ba30d..10595661 100644 --- a/tox.ini +++ b/tox.ini @@ -51,7 +51,7 @@ commands = sphinx-build \ --keep-going \ -TW \ - -b html \ + -b dirhtml \ docs/ docs/_build/html description = Build documentation and API through Sphinx @@ -83,6 +83,7 @@ commands = --re-ignore docs/usage/sub_expr_f? \ --watch docs \ --watch src \ + -b dirhtml \ docs/ docs/_build/html description = Set up a server to directly preview changes to the HTML pages @@ -97,7 +98,7 @@ commands = sphinx-build \ --keep-going \ -TW \ - -b html \ + -b dirhtml \ docs/ docs/_build/html description = Build documentation through Sphinx WITH output of Jupyter notebooks @@ -130,6 +131,7 @@ commands = --re-ignore docs/usage/sub_expr_f? \ --watch docs \ --watch src \ + -b dirhtml \ docs/ docs/_build/html description = Set up a server to directly preview changes to the HTML pages From eec7322ea9ccc462cc5075eb49dd936c518705d5 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Sun, 21 Jan 2024 00:03:45 +0100 Subject: [PATCH 4/4] DOC: switch to source code link button (#516) * MAINT: remove docstring from `conf.py` * MAINT: remove redundant `master_doc` and `source_suffix` * MAINT: sort `html_theme_options` --- docs/conf.py | 29 +++++++++-------------------- 1 file changed, 9 insertions(+), 20 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3f4380df..50cf8789 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,9 +1,3 @@ -"""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 -""" - from __future__ import annotations import os @@ -179,14 +173,6 @@ def get_tensorflow_url() -> str: "type": "url", }, ], - "logo": {"text": REPO_TITLE}, - "repository_url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}", - "repository_branch": BRANCH, - "path_to_docs": "docs", - "use_download_button": True, - "use_edit_page_button": True, - "use_issues_button": True, - "use_repository_button": True, "launch_buttons": { "binderhub_url": "https://mybinder.org", "colab_url": "https://colab.research.google.com", @@ -195,8 +181,17 @@ def get_tensorflow_url() -> str: "thebe": True, "thebelab": True, }, + "logo": {"text": REPO_TITLE}, + "path_to_docs": "docs", + "repository_branch": BRANCH, + "repository_url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}", "show_navbar_depth": 2, "show_toc_level": 2, + "use_download_button": False, + "use_edit_page_button": True, + "use_issues_button": True, + "use_repository_button": True, + "use_source_button": True, } html_title = REPO_TITLE intersphinx_mapping = { @@ -222,7 +217,6 @@ def get_tensorflow_url() -> str: linkcheck_ignore = [ "https://unix.stackexchange.com/a/129144", ] -master_doc = "index" modindex_common_prefix = [f"{PACKAGE}."] myst_enable_extensions = [ "amsmath", @@ -257,11 +251,6 @@ def get_tensorflow_url() -> str: project = REPO_TITLE pygments_style = "sphinx" release = get_package_version("tensorwaves") -source_suffix = { - ".ipynb": "myst-nb", - ".md": "myst-nb", - ".rst": "restructuredtext", -} thebe_config = { "repository_url": html_theme_options["repository_url"], "repository_branch": html_theme_options["repository_branch"],