Update documentation to use PyData theme [ci skip]

althonos · Aug 27, 2024 · 60b34c3 · 60b34c3
1 parent ea1f5b2
commit 60b34c3
Show file tree

Hide file tree

Showing 16 changed files with 1,017 additions and 76 deletions.
diff --git a/docs/_static/css/main.css b/docs/_static/css/main.css
@@ -0,0 +1,27 @@
+p {
+    text-align: justify;
+}
+
+/* a.reference strong {
+    font-weight: bold;
+    font-size: 90%;
+    color: #c7254e;
+    box-sizing: border-box;
+    font-family: Menlo,Monaco,Consolas,"Courier New",monospace;
+} */
+
+.field-list a.reference {
+    font-weight: bold;
+    font-size: 90%;
+    color: #c7254e;
+    box-sizing: border-box;
+    font-family: Menlo,Monaco,Consolas,"Courier New",monospace;
+}
+
+.class dd {
+    margin-left: 2%
+}
+
+.exception dd {
+    margin-left: 2%
+}
diff --git a/docs/_static/js/custom-icon.js b/docs/_static/js/custom-icon.js
@@ -0,0 +1,44 @@
+/*******************************************************************************
+ * Set a custom icon for pypi as it's not available in the fa built-in brands
+ */
+FontAwesome.library.add(
+  (faListOldStyle = {
+    prefix: "fa-custom",
+    iconName: "pypi",
+    icon: [
+      17.313, // viewBox width
+      19.807, // viewBox height
+      [], // ligature
+      "e001", // unicode codepoint - private use area
+      "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z", // svg path (https://simpleicons.org/icons/pypi.svg)
+    ],
+  }),
+);
+
+FontAwesome.library.add(
+  (faListOldStyle = {
+    prefix: "fa-custom",
+    iconName: "sword",
+    icon: [
+      256, // viewBox width
+      256, // viewBox height
+      [], // ligature
+      "e002", // unicode codepoint - private use area
+      "M221.65723,34.34326A8.00246,8.00246,0,0,0,216,32h-.02539l-63.79883.20117A8.00073,8.00073,0,0,0,146.0332,35.106L75.637,120.32275,67.31348,111.999A16.02162,16.02162,0,0,0,44.68555,112L32.001,124.68555A15.99888,15.99888,0,0,0,32,147.31348l20.88672,20.88769L22.94531,198.14258a16.01777,16.01777,0,0,0,.001,22.62695l12.28418,12.28418a16.00007,16.00007,0,0,0,22.62793,0L87.79883,203.1123,108.68652,224.001A16.02251,16.02251,0,0,0,131.31445,224L143.999,211.31445A15.99888,15.99888,0,0,0,144,188.68652l-8.32324-8.32324,85.21679-70.39648a8.00125,8.00125,0,0,0,2.90528-6.14258L224,40.02539A8.001,8.001,0,0,0,221.65723,34.34326Zm-13.84668,65.67822-83.49829,68.97706L111.314,156l54.34327-54.34277a8.00053,8.00053,0,0,0-11.31446-11.31446L100,144.686,87.00195,131.6875,155.97852,48.189l51.99609-.16357Z", // svg path (https://simpleicons.org/icons/pypi.svg)
+    ],
+  }),
+);
+
+FontAwesome.library.add(
+  (faListOldStyle = {
+    prefix: "fa-custom",
+    iconName: "knife",
+    icon: [
+      256, // viewBox width
+      256, // viewBox height
+      [], // ligature
+      "e003", // unicode codepoint - private use area
+      "M231.79883,32.2002a28.05536,28.05536,0,0,0-39.667.06933L18.27441,210.41211a8,8,0,0,0,3.92676,13.38281,155.06019,155.06019,0,0,0,34.957,4.00293c33.4209-.001,66.877-10.86914,98.32813-32.1748,31.74512-21.50391,50.14551-45.79981,50.91406-46.82325a8.00114,8.00114,0,0,0-.74316-10.457L186.919,119.60547l44.97753-47.90332A28.03445,28.03445,0,0,0,231.79883,32.2002ZM189.207,144.52148a225.51045,225.51045,0,0,1-43.10351,38.13184c-34.46973,23.23145-69.999,32.665-105.83887,28.13477l106.29492-108.915,23.30176,23.30175q.208.22852.43847.44434l.082.07617Z", // svg path (https://simpleicons.org/icons/pypi.svg)
+    ],
+  }),
+);
diff --git a/docs/_static/json/switcher.json b/docs/_static/json/switcher.json
@@ -0,0 +1,22 @@
+[
+    {
+        "name": "v0.4 (latest)",
+        "version": "0.4.0",
+        "url": "https://pyfamsa.readthedocs.io/en/v0.3.3/"
+    },
+    {
+        "name": "v0.3 (latest)",
+        "version": "0.3.2",
+        "url": "https://pyfamsa.readthedocs.io/en/v0.3.2/"
+    },
+    {
+        "name": "v0.2",
+        "version": "0.2.0",
+        "url": "https://pyfamsa.readthedocs.io/en/v0.2.0/"
+    },
+    {
+        "name": "v0.1",
+        "version": "0.1.1",
+        "url": "https://pyfamsa.readthedocs.io/en/v0.1.1/"
+    }
+]
diff --git a/docs/api/alignment.rst b/docs/api/alignment.rst
@@ -3,11 +3,6 @@ Alignment
 
 .. currentmodule:: pyfamsa
 
-
 .. autoclass:: pyfamsa.Alignment
    :inherited-members:
    :members:
-
-.. autoclass:: pyfamsa.GappedSequence
-  :inherited-members:
-  :members:
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -3,48 +3,62 @@ API Reference
 
 .. currentmodule:: pyfamsa
 
+Aligner
+-------
+
+.. autosummary::
+    :nosignatures:
+
+    Aligner
+
 .. toctree::
+   :caption: Aligner
    :hidden:
 
    aligner <aligner>
-   sequence <sequence>
-   alignment <alignment>
-   guide_tree <guide_tree>
 
 
-.. only:: html
+Sequence
+--------
 
-    Aligner
-    -------
+.. autosummary::
+    :nosignatures:
 
-    .. autosummary::
-        :nosignatures:
+    Sequence
+    GappedSequence
 
-        pyfamsa.Aligner
+.. toctree::
+   :caption: Sequence
+   :hidden:
 
-    Sequence
-    --------
+   sequence <sequence>
 
-    .. autosummary::
-        :nosignatures:
 
-        pyfamsa.Sequence
+Alignment
+---------
 
+.. autosummary::
+    :nosignatures:
 
     Alignment
-    ---------
 
-    .. autosummary::
-        :nosignatures:
+.. toctree::
+   :caption: Alignment
+   :hidden:
 
-        pyfamsa.Alignment
-        pyfamsa.GappedSequence
+   alignment <alignment>
 
 
+GuideTree
+---------
+
+.. autosummary::
+    :nosignatures:
+
     GuideTree
-    ---------
 
-    .. autosummary::
-        :nosignatures:
+.. toctree::
+   :caption: GuideTree
+   :hidden:
 
-        pyfamsa.GuideTree
+   guide_tree <guide_tree>
diff --git a/docs/api/sequence.rst b/docs/api/sequence.rst
@@ -6,3 +6,7 @@ Sequence
 .. autoclass:: pyfamsa.Sequence
    :inherited-members:
    :members:
+
+.. autoclass:: pyfamsa.GappedSequence
+  :inherited-members:
+  :members:
diff --git a/docs/changes.md b/docs/changes.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,7 +12,6 @@
 import re
 import semantic_version
 import shutil
-import sphinx_bootstrap_theme
 import sys
 
 # -- Path setup --------------------------------------------------------------
@@ -69,7 +68,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.todo",
     "sphinx.ext.extlinks",
-    "sphinx_bootstrap_theme",
+    "sphinx_design",
     "recommonmark",
     "nbsphinx",
 ]
@@ -103,54 +102,54 @@
 # 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 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_static_path = ['_static/js', '_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", cfgparser.get("metadata", "url").strip(), True)
-    ] + [
-        (k, v, True)
-        for k, v in project_urls.items()
-        if k in {"Zenodo", "PyPI"}
+    "external_links": [],
+    "show_toc_level": 2,
+    "use_edit_page_button": True,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/althonos/pyfamsa",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/pyfamsa",
+            "icon": "fa-custom fa-pypi",
+        },
     ],
-    "admonition_use_panel": True,
+    "logo": {
+        "text": "PyFAMSA",
+        # "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://pyfamsa.readthedocs.io/en/latest/_static/switcher.json",
+        "version_match": version,
+    }
 }
 
-# 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"],
-    "api/*": ["localtoc.html"],
-    "examples/*": ["localtoc.html"],
+html_context = {
+    "github_user": "althonos",
+    "github_repo": "pyfamsa",
+    "github_version": "main",
+    "doc_path": "docs",
 }
 
 # -- Options for HTMLHelp output ---------------------------------------------
@@ -185,7 +184,6 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "biopython": ("https://biopython.org/docs/latest/api/", None),
     "scoring_matrices": ("https://scoring-matrices.readthedocs.io/en/stable", None),
 }
 

diff --git a/docs/contributing.md b/docs/contributing.md
diff --git a/docs/guide/changes.md b/docs/guide/changes.md
@@ -0,0 +1 @@
+../../CHANGELOG.md
diff --git a/docs/guide/contributing.md b/docs/guide/contributing.md
@@ -0,0 +1 @@
+../../CONTRIBUTING.md