Merge pull request #533 from star-dust-ctrl/master

Update the style of documentation

.readthedocs.yaml

@@ -4,20 +4,13 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.9"
-  jobs:
-    pre_install:
-      - pip install --no-cache-dir pip --upgrade
-      - pip install --no-cache-dir pybind11[global]
-    pre_build:
-      - pip install --no-cache-dir -r docs/requirements.txt
-  apt_packages:
-    - graphviz
+
+sphinx:
+   configuration: docs/conf.py
 
 python:
   install:
-    - requirements: docs/requirements.txt
-    - method: pip
-      path: python
+  - requirements: docs/requirements.txt
 
 # Build PDF
 formats:

docs/_static/custom.css

@@ -0,0 +1,66 @@
+/* Background of stable should be green */
+.version-switcher__container a[data-version-name*="stable"] {
+  position: relative;
+}
+
+.version-switcher__container a[data-version-name*="stable"] span {
+  color: var(--pst-color-success);
+}
+
+.version-switcher__container a[data-version-name*="stable"] span:before {
+  content: "";
+  width: 100%;
+  height: 100%;
+  position: absolute;
+  left: 0;
+  top: 0;
+  background-color: var(--pst-color-success);
+  opacity: 0.1;
+}
+
+/* custom CSS classes (used in docs/user_guide/extending.rst) NOTE: the begin
+ *  and end markers are necessary for partial file includes! don't remove them.
+ */
+
+/* begin-custom-color/* <your static path>/custom.css */
+
+div.admonition.admonition-olive {
+  border-color: olive;
+}
+div.admonition.admonition-olive > .admonition-title:before {
+  background-color: olive;
+}
+div.admonition.admonition-olive > .admonition-title:after {
+  color: olive;
+}
+/* end-custom-color */
+
+/* begin-custom-icon/* <your static path>/custom.css */
+
+div.admonition.admonition-icon > .admonition-title:after {
+  content: "\f24e"; /* the fa-scale icon */
+}
+/* end-custom-icon */
+
+/* begin-custom-youtube/* <your static path>/custom.css */
+
+div.admonition.admonition-youtube {
+  border-color: #ff0000; /* YouTube red */
+}
+div.admonition.admonition-youtube > .admonition-title:before {
+  background-color: #ff0000;
+}
+div.admonition.admonition-youtube > .admonition-title:after {
+  color: #ff0000;
+  content: "\f26c"; /* fa-solid fa-tv */
+}
+/* end-custom-youtube */
+
+.sphx-glr-thumbcontainer[tooltip]:hover::before,
+.sphx-glr-thumbcontainer[tooltip]:hover::after {
+    display: none;
+}
+:root, html[data-theme="light"], body[data-theme="light"]{
+  --sg-download-a-background-image: linear-gradient(to bottom, #20B2AA, #ADD8E6);
+  --sg-download-a-hover-background-color: #ADD8E6;
+}

docs/_static/switcher.json

@@ -0,0 +1,12 @@
+[
+  {
+    "name": "latest",
+    "version": "latest",
+    "url": "https://abess.readthedocs.io/en/latest/"
+  },
+  {
+    "name": "0.4.7 (stable)",
+    "version": "0.4.7",
+    "url": "https://abess.readthedocs.io/en/latest/"
+  }
+]

docs/_templates/autoapi/index.rst

@@ -0,0 +1,15 @@
+API References
+==============
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages %}
+   {% if page.top_level_object and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

docs/_templates/autoapi/python/attribute.rst

@@ -0,0 +1 @@
+{% extends "python/data.rst" %}

docs/_templates/autoapi/python/class.rst

@@ -0,0 +1,50 @@
+{% if obj.display %}
+.. py:{{ obj.type }}:: {{ obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %}
+{% for (args, return_annotation) in obj.overloads %}
+   {{ " " * (obj.type | length) }}   {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
+{% endfor %}
+
+
+   {% if obj.bases %}
+   {% if "show-inheritance" in autoapi_options %}
+   Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
+   {% endif %}
+
+
+   {% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
+   .. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
+      :parts: 1
+      {% if "private-members" in autoapi_options %}
+      :private-bases:
+      {% endif %}
+
+   {% endif %}
+   {% endif %}
+   {% if obj.docstring %}
+   {{ obj.docstring|indent(3) }}
+   {% endif %}
+   {% if "inherited-members" in autoapi_options %}
+   {% set visible_classes = obj.classes|selectattr("display")|list %}
+   {% else %}
+   {% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %}
+   {% endif %}
+   {% for klass in visible_classes %}
+   {{ klass.render()|indent(3) }}
+   {% endfor %}
+   {% if "inherited-members" in autoapi_options %}
+   {% set visible_attributes = obj.attributes|selectattr("display")|list %}
+   {% else %}
+   {% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
+   {% endif %}
+   {% for attribute in visible_attributes %}
+   {{ attribute.render()|indent(3) }}
+   {% endfor %}
+   {% if "inherited-members" in autoapi_options %}
+   {% set visible_methods = obj.methods|selectattr("display")|list %}
+   {% else %}
+   {% set visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
+   {% endif %}
+   {% for method in visible_methods %}
+   {{ method.render()|indent(3) }}
+   {% endfor %}
+{% endif %}

docs/_templates/autoapi/python/data.rst

@@ -0,0 +1,32 @@
+{% if obj.display %}
+.. py:{{ obj.type }}:: {{ obj.name }}
+   {%+ if obj.value is not none or obj.annotation is not none -%}
+   :annotation:
+        {%- if obj.annotation %} :{{ obj.annotation }}
+        {%- endif %}
+        {%- if obj.value is not none %} = {%
+            if obj.value is string and obj.value.splitlines()|count > 1 -%}
+                Multiline-String
+
+    .. raw:: html
+
+        <details><summary>Show Value</summary>
+
+    .. code-block:: text
+        :linenos:
+
+        {{ obj.value|indent(width=8) }}
+
+    .. raw:: html
+
+        </details>
+
+            {%- else -%}
+                {{ obj.value|string|truncate(100) }}
+            {%- endif %}
+        {%- endif %}
+    {% endif %}
+
+
+   {{ obj.docstring|indent(3) }}
+{% endif %}

docs/_templates/autoapi/python/exception.rst

@@ -0,0 +1 @@
+{% extends "python/class.rst" %}

docs/_templates/autoapi/python/function.rst

@@ -0,0 +1,18 @@
+{% if obj.display %}
+.. py:function:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
+
+{% for (args, return_annotation) in obj.overloads %}
+              {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
+
+{% endfor %}
+   {% if sphinx_version >= (2, 1) %}
+   {% for property in obj.properties %}
+   :{{ property }}:
+   {% endfor %}
+   {% endif %}
+
+   {% if obj.docstring %}
+   {{ obj.docstring|indent(3) }}
+   {% else %}
+   {% endif %}
+{% endif %}

docs/_templates/autoapi/python/method.rst

@@ -0,0 +1,27 @@
+{%- if obj.display %}
+{% if sphinx_version >= (2, 1) %}
+.. py:method:: {{ obj.short_name }}({{ obj.args }}){% if obj.return_annotation is not none %} -> {{ obj.return_annotation }}{% endif %}
+
+{% for (args, return_annotation) in obj.overloads %}
+            {{ obj.short_name }}({{ args }}){% if return_annotation is not none %} -> {{ return_annotation }}{% endif %}
+
+{% endfor %}
+   {% if obj.properties %}
+   {% for property in obj.properties %}
+   :{{ property }}:
+   {% endfor %}
+
+   {% else %}
+
+   {% endif %}
+{% else %}
+.. py:{{ obj.method_type }}:: {{ obj.short_name }}({{ obj.args }})
+{% for (args, return_annotation) in obj.overloads %}
+   {{ " " * (obj.method_type | length) }}   {{ obj.short_name }}({{ args }})
+{% endfor %}
+
+{% endif %}
+   {% if obj.docstring %}
+   {{ obj.docstring|indent(3) }}
+   {% endif %}
+{% endif %}