DOC: [FEATURE] Improve documentation generally

- use piccolo theme - add ndk fpga logo - improve deprecation warnings - improve welcome page to make user more interested
CESNET · Oct 25, 2024 · ddccb0e · ddccb0e
1 parent 119e2d1
commit ddccb0e
Show file tree

Hide file tree

Showing 13 changed files with 288 additions and 75 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -16,7 +16,7 @@ jobs:
       - name: Setup and build
         run: |
           sudo apt-get install python3-pip
-          pip3 install sphinx sphinx-vhdl sphinx_rtd_theme GitPython
+          pip3 install sphinx sphinx-vhdl sphinx_rtd_theme piccolo_theme GitPython
           mkdir public
           mkdir public/html
           cp doc/source/index.html public/html/

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -16,7 +16,7 @@ pages:
     - apk add git
     - pip install -U GitPython
     - pip install -U sphinx
-    - pip install -U sphinx-rtd-theme
+    - pip install -U piccolo_theme
     - pip install -U sphinx-vhdl
     - echo "Hotfix detached head, causing trouble in GitPython:"
     - git checkout $CI_COMMIT_BRANCH

diff --git a/README.md b/README.md
@@ -60,7 +60,7 @@ First, you need to install a few Python packages:
 $ pip3 install --user GitPython
 $ pip3 install --user sphinx
 $ pip3 install --user sphinx-vhdl
-$ pip3 install --user sphinx_rtd_theme
+$ pip3 install --user piccolo_theme
 ```
 
 Then the documentation is generated simply by issuing these two commands:

diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html
@@ -0,0 +1,115 @@
+{% extends "basic/layout.html" %} {%- block body_tag %}
+<body
+    data-dark_mode_code_blocks="{{ 'true' if theme_dark_mode_code_blocks else 'false' }}"
+>
+    {% endblock %} {%- block header %}
+
+    <div id="top_nav">
+        {% if theme_banner_text and theme_banner_text != 'false' %} {% include
+        "./components/notification_banner.html" %} {% endif %}
+
+        <nav>
+            {% if logo_url %} {% set nav_title = '<img
+                src="' + logo_url + '"
+            />' %} {% else %} {% set nav_title = shorttitle %} {% endif %}
+
+            <p id="toggle_sidebar">
+                <a href="#" title="Toggle sidebar">|||</a>
+            </p>
+            <h1>
+                <a href="{{ pathto(root_doc)|e }}" title="Go to homepage"
+                    >{{ nav_title }}</a
+                >
+            </h1>
+
+            {%- if theme_source_url %} {% include
+            "./components/source_link.html" %} {% endif %} {% include
+            "./components/dark_mode_toggle.html" %} {%- if pagename != "search"
+            %}
+            <p class="mobile_search_link">
+                <a href="{{ pathto('search') }}" title="Search">
+                    <svg
+                        xmlns="http://www.w3.org/2000/svg"
+                        viewBox="0 0 65 64"
+                        fill-rule="evenodd"
+                        stroke-linejoin="round"
+                        stroke-miterlimit="2"
+                    >
+                        <path
+                            d="M14.873 40.009c-2.315-3.943-3.642-8.532-3.642-13.429C11.231 11.91 23.141 0 37.811 0s26.58 11.91 26.58 26.58-11.91 26.58-26.58 26.58a26.44 26.44 0 0 1-14.277-4.161L9.739 62.794a3.12 3.12 0 0 1-4.413 0L.913 58.382c-1.217-1.218-1.217-3.196 0-4.413l13.96-13.96zM37.811 8.054c10.225 0 18.526 8.301 18.526 18.526s-8.301 18.526-18.526 18.526-18.526-8.301-18.526-18.526S27.586 8.054 37.811 8.054z"
+                            fill="#fff"
+                        />
+                    </svg>
+                </a>
+            </p>
+            {% endif %}
+
+            <div class="searchbox_wrapper">
+                {% include "basic/searchbox.html" %}
+            </div>
+        </nav>
+    </div>
+    {% endblock %} {%- block sidebar1 %} {{ sidebar() }} {%- block sidebarlogo
+    %}{% endblock %} {% endblock %} {%- block sidebar2 %} {% if display_toc %}
+    <div id="show_right_sidebar">
+        <p>
+            <a class="toggle_right_sidebar" href="#"
+                ><span class="icon">&lt;</span><span>Page contents</span></a
+            >
+        </p>
+    </div>
+
+    <div id="right_sidebar">
+        <p>
+            <a class="toggle_right_sidebar" href="#"
+                ><span class="icon">&gt;</span><span>Page contents:</span></a
+            >
+        </p>
+        <div class="page_toc">{{ toc }}</div>
+    </div>
+    {% endif %} {% endblock %} {%- block relbar1 %}{% endblock %} {%- block
+    scripts %} {{- script() }}
+    <script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
+    <script src="{{ pathto('_static/js/petite-vue.js', 1) }}"></script>
+    {%- endblock %} {%- block relbar2 %}
+    <div class="button_nav_wrapper">
+        <div class="button_nav">
+            <div class="left">
+                {% if prev %}
+                <a href="{{ prev.link }}">
+                    <span class="icon">&lt;</span
+                    ><span>{{ prev.title }}</span></a
+                >
+                {% endif %}
+            </div>
+
+            <div class="right">
+                {% if next %}
+                <a href="{{ next.link }}"
+                    ><span>{{ next.title }}</span
+                    ><span class="icon">&gt;</span></a
+                >
+                {% endif %}
+            </div>
+        </div>
+    </div>
+    {% endblock %} {%- block footer %} {{ super() }}
+    <div
+        style="
+            box-sizing: border-box;
+            padding-top: 0.2rem;
+            font-size: 0.7rem;
+            text-align: center;
+            color: var(--faintFontColor);
+        "
+    >
+        {{ version }}
+    </div>
+
+    <p id="theme_credit">
+        {% if theme_show_theme_credit %}Styled using the
+        <a href="https://github.com/piccolo-orm/piccolo_theme">Piccolo Theme</a
+        >{% endif %}
+    </p>
+    {%- endblock %}
+</body>
diff --git a/doc/source/base.rst b/doc/source/base.rst
@@ -2,7 +2,7 @@ Basic Tools
 ===========
 
 This chapter describes the basic components such as FIFOs, RAMs, multiplexers, encoders, decoders, etc.
-The basic components are typically located in the ``comp/base/`` directory in the OFM repository.
+The basic components are typically located in the ``comp/base/`` directory in the NDK-FPGA repository.
 
 .. toctree::
    :maxdepth: 1
@@ -12,6 +12,5 @@ The basic components are typically located in the ``comp/base/`` directory in th
    memory
    fifo
    dsp
-   shift
    logic
    misc
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -18,10 +18,10 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'NDK-FPGA Docs'
+project = 'NDK-FPGA'
 copyright = str(current_year) + ', CESNET z.s.p.o.'
 author = 'CESNET TMC'
-version = 'Git branch: ' + str(git_branch) + ', <br> Git hash: ' + str(git_sha_short)
+version = 'Git branch: ' + str(git_branch) + '<br>Git hash: ' + str(git_sha_short)
 
 # -- General configuration ---------------------------------------------------
 
@@ -30,8 +30,9 @@
 # ones.
 extensions = [
     "ndk-fpga",
-    "sphinx_rtd_theme",
-    "sphinxvhdl.vhdl"
+    "piccolo_theme",
+    "sphinxvhdl.vhdl",
+    "sphinx.ext.autosectionlabel"
 ]
 
 vhdl_autodoc_source_path = (Path(__file__).parent.parent.parent).resolve()
@@ -50,18 +51,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = 'piccolo_theme'
 html_theme_options = {
-    'collapse_navigation': True,
-    'sticky_navigation': True,
-    'navigation_depth': 4,
-    'includehidden': True,
-    'display_version': True,
+    "globaltoc_maxdepth": 4,
+    "banner_hiding": "permanent",
+    "show_theme_credit": False,
 }
 
+html_logo = "img/ndk_fpga_logo_simple.png"
+
 # 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_style = 'css/theme_overrides.css'
diff --git a/doc/source/fifo.rst b/doc/source/fifo.rst
@@ -6,9 +6,17 @@ FIFO components
 Dual clock (asynchronous) FIFOs
 -------------------------------
 
-**ASFIFO** - Behavioral dual clock FIFO implementation based on LUTMEMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use ASFIFOX!``
+**ASFIFO** - Behavioral dual clock FIFO implementation, based on LUTMEMs and optimized for Xilinx only. Includes status signal.
 
-**ASFIFO_BRAM** - Behavioral dual clock FIFO implementation based on BRAMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use ASFIFOX!``
+.. warning::
+   .. deprecated:: 0.7.0
+      This component is obsolete and is a candidate for removal, use **ASFIFOX** instead.
+
+**ASFIFO_BRAM** - Behavioral dual clock FIFO implementation, based on BRAMs and optimized for Xilinx only. Includes status signal.
+
+.. warning::
+   .. deprecated:: 0.7.0
+      This component is obsolete and is a candidate for removal, use **ASFIFOX** instead.
 
 **ASFIFO_BRAM_BLOCK** - Similar to ASFIFO_BRAM but with extra signal to mark end of input data block, output remains in empty state until such mark is received. Located in the same folder as ASFIFO_BRAM.
 
@@ -34,13 +42,25 @@ Detailed :ref:`documentation can be found here<asfifox>`.
 Single clock FIFOs
 ------------------
 
-**FIFO** - Behavioral FIFO implementation based on LUTMEMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use FIFOX!``
+**FIFO** - Behavioral FIFO implementation, based on LUTMEMs and optimized for Xilinx only. Includes status signal.
+
+.. warning::
+   .. deprecated:: 0.7.0
+      This component is obsolete and is a candidate for removal, use **FIFOX** instead.
 
-**FIFO_BRAM** - Behavioral FIFO implementation based on BRAMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use FIFOX!``
+**FIFO_BRAM** - Behavioral FIFO implementation, based on BRAMs and optimized for Xilinx only. Includes status signal.
+
+.. warning::
+   .. deprecated:: 0.7.0
+      This component is obsolete and is a candidate for removal, use **FIFOX** instead.
 
 **FIFO_BRAM_XILINX** - Structural implementation of FIFO based on Xilinx specific BRAM FIFO primitives (no extra logic). Include almost full and almost empty signal.
 
-**FIFO_N1** - Behavioral implementation of FIFO with multiple write ports, it based on LUTMEMs and optimized for Xilinx only. ``OBSOLETE, use FIFOX_MULTI!``
+**FIFO_N1** - Behavioral implementation of FIFO with multiple write ports, it is based on LUTMEMs and optimized for Xilinx only.
+
+.. warning::
+   .. deprecated:: 0.7.0
+      This component is obsolete and is a candidate for removal, use **FIFOX** instead.
 
 **FIFOX** - Universal FIFO for Xilinx and Intel FPGAs. It support various memory implementation: LUTMEMs, BRAMs, URAMs (Xilinx only) and shift-registers in LUT slices (effective on Xilinx only).
 Include almost full, almost empty and status signal. Possible automatic selection of a suitable memory implementation. Detailed :ref:`documentation can be found here<fifox>`.
@@ -50,7 +70,11 @@ Include almost full, almost empty and status signal. Possible automatic selectio
 **MULTI_FIFO** - Behavioral implementation of FIFO for Xilinx and Intel FPGAs with multiple independent channels. It support various memory implementation: LUTMEMs, BRAMs, URAMs (Xilinx only).
 The memory type is selected automatically.
 
-**SH_FIFO** - Behavioral FIFO implementation based on shift-registers in LUT slices and optimized for Xilinx only. ``OBSOLETE, use FIFOX!``
+**SH_FIFO** - Behavioral FIFO implementation, based on shift-registers in LUT slices and optimized for Xilinx only.
+
+.. warning::
+   .. deprecated:: 0.7.0
+      This component is obsolete and is a candidate for removal, use **FIFOX** instead.
 
 .. toctree::
    :maxdepth: 1

diff --git a/doc/source/img/ndk_fpga_logo.png b/doc/source/img/ndk_fpga_logo.png