Skip to content

Commit

Permalink
Merge branch 'gurka-better-docs' into 'devel'
Browse files Browse the repository at this point in the history
DOC: [FEATURE] Documentation rework for possible PR

See merge request ndk/ndk-fpga!73
  • Loading branch information
jakubcabal committed Oct 25, 2024
2 parents d2c22dc + 83b34be commit ea2302f
Show file tree
Hide file tree
Showing 14 changed files with 301 additions and 86 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/doc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down
24 changes: 12 additions & 12 deletions .gitlab-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,23 @@ variables:
GIT_SUBMODULE_STRATEGY: recursive

include:
- local: 'tests/ci/check.gitlab-ci.yaml'
- local: "tests/ci/check.gitlab-ci.yaml"

pages:
stage: deploy
image: python:3.9-alpine
script:
- apk add git
- pip install -U GitPython
- pip install -U sphinx
- pip install -U sphinx-rtd-theme
- pip install -U sphinx-vhdl
- echo "Hotfix detached head, causing trouble in GitPython:"
- git checkout $CI_COMMIT_BRANCH
- git status
- sphinx-build -b html doc/source/ public
- apk add git
- pip install -U GitPython
- pip install -U sphinx
- pip install -U piccolo_theme
- pip install -U sphinx-vhdl
- echo "Hotfix detached head, causing trouble in GitPython:"
- git checkout $CI_COMMIT_BRANCH
- git status
- sphinx-build -b html doc/source/ public
artifacts:
paths:
- public
- public
only:
- devel
- devel
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
- Improve documentation
- Improve documentation looks

## [0.7.2] - 2024-10-17

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
115 changes: 115 additions & 0 deletions doc/source/_templates/layout.html
Original file line number Diff line number Diff line change
@@ -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>
3 changes: 1 addition & 2 deletions doc/source/base.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -12,6 +12,5 @@ The basic components are typically located in the ``comp/base/`` directory in th
memory
fifo
dsp
shift
logic
misc
23 changes: 11 additions & 12 deletions doc/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 ---------------------------------------------------

Expand All @@ -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()
Expand All @@ -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'
36 changes: 30 additions & 6 deletions doc/source/fifo.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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>`.
Expand All @@ -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
Expand Down
Binary file added doc/source/img/ndk_fpga_logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit ea2302f

Please sign in to comment.