Update documentation to use PyData theme [ci skip]

althonos · Sep 14, 2024 · 25251ff · 25251ff
1 parent 200fe3b
commit 25251ff
Show file tree

Hide file tree

Showing 12 changed files with 134 additions and 75 deletions.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,10 +1,11 @@
 semantic_version ~=2.8
-sphinx ~=7.0
-# sphinx-bootstrap-theme ~=0.7
-https://github.com/althonos/sphinx-bootstrap-theme/archive/master.zip
-recommonmark ~=0.6
-nbsphinx ~=0.5
+sphinx >=4.0
+recommonmark ~=0.7
 pygments-style-monokailight ~=0.4
-ipython ~=8.21
+ipython ~=7.19
 pygments ~=2.4
-fastobo ~=0.12.0
+nbsphinx ~=0.8
+sphinxcontrib-jquery ~=4.1
+sphinx-design
+pydata-sphinx-theme
+fastobo ~=0.12.0
diff --git a/docs/source/api.rst → docs/source/api/index.rst b/docs/source/api.rst → docs/source/api/index.rst
@@ -14,7 +14,12 @@ An abstraction over a :math:`\mathcal{SHOIN}^\mathcal{(D)}` ontology.
 .. autosummary::
    :nosignatures:
    :template: summary.rst
-   :toctree: api/
+
+   pronto.Ontology
+
+.. toctree::
+   :hidden:
+   :caption: Ontology
 
    pronto.Ontology
 
@@ -34,7 +39,17 @@ obtained from methods of existing `Ontology` or `Entity` instances, such as
 .. autosummary::
    :nosignatures:
    :template: summary.rst
-   :toctree: api/
+
+   pronto.Entity
+   pronto.Relationship
+   pronto.Synonym
+   pronto.Term
+   pronto.TermSet
+
+
+.. toctree::
+   :hidden:
+   :caption: View Layer
 
    pronto.Entity
    pronto.Relationship
@@ -52,11 +67,17 @@ instantiated directly, but are reachable through the right property on `Entity`
 instances.
 
 .. autosummary::
-    :nosignatures:
-    :template: summary.rst
-    :toctree: api/
+   :nosignatures:
+   :template: summary.rst
+
+   pronto.entity.attributes.Relationships
+
+
+.. toctree::
+   :hidden:
+   :caption: View Collections
 
-    pronto.entity.attributes.Relationships
+   pronto.entity.attributes.Relationships
 
 
 Model Layer
@@ -71,7 +92,19 @@ accessed and mutated directly.*
 .. autosummary::
    :nosignatures:
    :template: summary.rst
-   :toctree: api/
+
+   pronto.Metadata
+   pronto.Definition
+   pronto.Subset
+   pronto.SynonymType
+   pronto.LiteralPropertyValue
+   pronto.ResourcePropertyValue
+   pronto.Xref
+
+
+.. toctree::
+   :hidden:
+   :caption: Model Layer
 
    pronto.Metadata
    pronto.Definition
@@ -92,7 +125,16 @@ exception of custom parser implementations.
 .. autosummary::
    :nosignatures:
    :template: summary.rst
-   :toctree: api/
+   :toctree:
+
+   pronto.RelationshipData
+   pronto.SynonymData
+   pronto.TermData
+
+
+.. toctree::
+   :hidden:
+   :caption: Data Layer
 
    pronto.RelationshipData
    pronto.SynonymData
@@ -104,8 +146,9 @@ Warnings
 
 .. toctree::
    :hidden:
+   :caption: Warnings
 
-   warnings <api/warnings>
+   warnings <warnings>
 
 .. autosummary::
    :nosignatures:

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,7 +12,6 @@
 import re
 import semantic_version
 import shutil
-import sphinx_bootstrap_theme
 import sys
 
 # -- Path setup --------------------------------------------------------------
@@ -79,7 +78,7 @@ def setup(app):
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
-    "sphinx_bootstrap_theme",
+    "sphinx_design",
     "nbsphinx",
     "recommonmark",
     "IPython.sphinxext.ipython_console_highlighting",
@@ -97,13 +96,6 @@ def setup(app):
 # The master toctree document.
 master_doc = "index"
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
 # 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 .
@@ -121,56 +113,58 @@ def setup(app):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "bootstrap"
+html_theme = "pydata_sphinx_theme"
 
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+# 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/js', '_static/bibtex', '_static/css', '_static/json']
+html_js_files = ["custom-icon.js"]
+html_css_files = ["custom.css"]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = {
-    # Bootswatch (http://bootswatch.com/) theme.
-    "bootswatch_theme": "flatly",
-    # Choose Bootstrap version.
-    "bootstrap_version": "3",
-    # Tab name for entire site. (Default: "Site")
-    "navbar_site_name": "Documentation",
-    # HTML navbar class (Default: "navbar") to attach to <div> element.
-    # For black navbar, do "navbar navbar-inverse"
-    "navbar_class": "navbar",
-    # Render the next and previous page links in navbar. (Default: true)
-    "navbar_sidebarrel": True,
-    # Render the current pages TOC in the navbar. (Default: true)
-    "navbar_pagenav": False,
-    # A list of tuples containing pages or urls to link to.
-    "navbar_links": [
-        ("GitHub", _parser.get("metadata", "home-page").strip(), True),
-        ("CI", project_urls["CI"], True)
+    "show_toc_level": 2,
+    "use_edit_page_button": True,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/althonos/pronto",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/pronto",
+            "icon": "fa-custom fa-pypi",
+        },
     ],
-    "admonition_use_panel": True,
+    "logo": {
+        "text": "Pronto",
+        # "image_light": "_images/logo.png",
+        # "image_dark": "_images/logo.png",
+    },
+    "navbar_start": ["navbar-logo", "version-switcher"],
+    "navbar_align": "left",
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+    "switcher": {
+        "json_url": "https://pronto.readthedocs.io/en/latest/_static/switcher.json",
+        "version_match": version,
+    }
 }
 
-# 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"]
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-html_sidebars = {
-    "*": ["localtoc.html"],
-    "examples/*": ["localtoc.html"],
-    "api/*": ["localtoc.html"],
+html_context = {
+    "github_user": "althonos",
+    "github_repo": "pronto",
+    "github_version": "main",
+    "doc_path": "docs",
 }
 
+html_favicon = '_images/favicon.ico'
+
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
@@ -223,3 +217,13 @@ def setup(app):
 # -- Options for nbsphinx extension ------------------------------------------
 
 nbsphinx_execute = 'auto'
+
+# -- Options for extlinks extension ------------------------------------------
+
+extlinks = {
+    'doi': ('https://doi.org/%s', 'doi:%s'),
+    'pmid': ('https://pubmed.ncbi.nlm.nih.gov/%s', 'PMID:%s'),
+    'pmc': ('https://www.ncbi.nlm.nih.gov/pmc/articles/PMC%s', 'PMC%s'),
+    'isbn': ('https://www.worldcat.org/isbn/%s', 'ISBN:%s'),
+    'wiki': ('https://en.wikipedia.org/wiki/%s', '%s'),
+}
diff --git a/docs/source/about.rst → docs/source/guide/about.rst b/docs/source/about.rst → docs/source/guide/about.rst
diff --git a/docs/source/guide/changes.md b/docs/source/guide/changes.md
@@ -0,0 +1 @@
+../../../CHANGELOG.md
diff --git a/docs/source/examples/index.rst → docs/source/guide/examples/index.rst b/docs/source/examples/index.rst → docs/source/guide/examples/index.rst
diff --git a/docs/source/examples/ms.ipynb → docs/source/guide/examples/ms.ipynb b/docs/source/examples/ms.ipynb → docs/source/guide/examples/ms.ipynb
diff --git a/docs/source/guide/index.rst b/docs/source/guide/index.rst
@@ -0,0 +1,19 @@
+User Guide
+==========
+
+This section contains guides and documents about Pronto usage.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+
+    Installation <install>
+    Examples <examples/index>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Resources
+
+   Update Guide <updating> 
+   Changelog <changes>
+   Copyright Notice <copyright>
diff --git a/docs/source/install.rst → docs/source/guide/install.rst b/docs/source/install.rst → docs/source/guide/install.rst
diff --git a/docs/source/updating.rst → docs/source/guide/updating.rst b/docs/source/updating.rst → docs/source/guide/updating.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -66,7 +66,7 @@ Setup
 
 Run ``pip install pronto`` in a shell to download the latest release and all
 its dependencies from PyPi, or have a look at the
-:doc:`Installation page <install>` to find other ways to install ``pronto``.
+:doc:`Installation page <guide/install>` to find other ways to install ``pronto``.
 
 .. note::
 
@@ -85,13 +85,8 @@ Library
 .. toctree::
    :maxdepth: 2
 
-   Installation <install>
-   Examples <examples/index>
-   Update Guide <updating>
-   API Reference <api>
-   To-do <todo>
-   Changelog <changes>
-   About <about>
+   User Guide <guide/index>
+   API Reference <api/index>
 
 
 Indices and tables

diff --git a/docs/source/todo.rst b/docs/source/todo.rst