diff --git a/.readthedocs.yml b/.readthedocs.yml index 0a01bb60e..1d335c1ab 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,25 +1,26 @@ --- -# .readthedocs.yaml -# Read the Docs configuration file +# Read the Docs configuration file for Sphinx projects # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required version: 2 -# Set the version of Python and other tools you might need +# Set the OS, Python version and other tools you might need build: - os: ubuntu-20.04 + os: ubuntu-22.04 tools: python: '3.10' -# Build documentation in the docs/ directory with Sphinx +# Build documentation in the "docs/" directory with Sphinx sphinx: configuration: docs/source/conf.py + builder: html + # Let the build fail if there are any warnings + fail_on_warning: true -# If using Sphinx, optionally build your docs in additional formats such as PDF -# formats: -# - pdf - +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html python: install: - method: pip diff --git a/aiidalab_widgets_base/bug_report.py b/aiidalab_widgets_base/bug_report.py index a37eb681c..5a4944814 100644 --- a/aiidalab_widgets_base/bug_report.py +++ b/aiidalab_widgets_base/bug_report.py @@ -147,16 +147,18 @@ def install_create_github_issue_exception_handler(output, url, labels=None): Example: -------- - ```python - output = ipw.Output() - install_create_github_issue_exception_handler( - output, - url='https://github.com/aiidalab/aiidalab-qe/issues/new', - labels=('bug', 'automated-report')) - - with output: - display(welcome_message, app_with_work_chain_selector, footer) - ``` + .. highlight:: python + .. code-block:: python + + output = ipw.Output() + install_create_github_issue_exception_handler( + output, + url='https://github.com/aiidalab/aiidalab-qe/issues/new', + labels=('bug', 'automated-report')) + + with output: + display(welcome_message, app_with_work_chain_selector, footer) + """ global _ORIGINAL_EXCEPTION_HANDLER diff --git a/aiidalab_widgets_base/computational_resources.py b/aiidalab_widgets_base/computational_resources.py index 9e6f60a69..8a68cce51 100644 --- a/aiidalab_widgets_base/computational_resources.py +++ b/aiidalab_widgets_base/computational_resources.py @@ -1224,12 +1224,8 @@ class ComputerDropdownWidget(ipw.VBox): """Widget to select a configured computer. Attributes: - value(computer UUID): Trait that points to the selected Computer instance. - It can be set to an AiiDA Computer UUID. It is linked to the - 'value' trait of `self._dropdown` widget. - computers(Dict): Trait that contains a dictionary (label => Computer UUID) for all - computers found in the AiiDA database. It is linked to the 'options' trait of - `self._dropdown` widget. + value(computer UUID): Trait that points to the selected Computer instance. It can be set to an AiiDA Computer UUID. It is linked to the 'value' trait of `self._dropdown` widget. + computers(Dict): Trait that contains a dictionary (label => Computer UUID) for all computers found in the AiiDA database. It is linked to the 'options' trait of `self._dropdown` widget. allow_select_disabled(Bool): Trait that defines whether to show disabled computers. """ diff --git a/docs/Makefile b/docs/Makefile index 218b9cf4c..e8de94c3b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,41 +1,23 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = +# 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 -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +.PHONY: help Makefile -.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext customdefault +# 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) -## Runs with nitty-pick and converting warnings into errors to -## make sure the documentation is properly written -customdefault: - $(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html - -all: html - -clean: - rm -r $(BUILDDIR) - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - - -view: - xdg-open $(BUILDDIR)/html/index.html +rebuild: + @ make -s clean html diff --git a/docs/source/_static/aiidalab_logo.png b/docs/source/_static/aiidalab_logo.png new file mode 100644 index 000000000..7900ed508 Binary files /dev/null and b/docs/source/_static/aiidalab_logo.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py index 03b7a4601..66cf0928d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,15 +24,10 @@ "sphinx.ext.mathjax", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", - "sphinxcontrib.contentui", "myst_nb", ] -jupyter_execute_notebooks = "off" - -intersphinx_mapping = { - "python": ("https://docs.python.org/3.9", None), -} +nb_execution_mode = "off" # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -92,6 +87,13 @@ html_theme = "pydata_sphinx_theme" +# The pydata-sphinx-theme already loads the bootstrap css. +panels_add_bootstrap_css = False + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "_static/aiidalab_logo.png" + # -- Modifications for Readthedocs ---------------------------------------- diff --git a/docs/source/widget-list/index.rst b/docs/source/widget-list/index.rst index 6c4f0d43c..71ca43782 100644 --- a/docs/source/widget-list/index.rst +++ b/docs/source/widget-list/index.rst @@ -12,9 +12,7 @@ See also the `corresponding git repository =2021.09.2 scikit-learn~=1.0.0 +docs = + sphinx + sphinx-design + pydata-sphinx-theme + myst-nb + [flake8] ignore =