Skip to content

Commit ea2302f

Browse files
jakubcabaljakubcabal
committed
Merge branch 'gurka-better-docs' into 'devel'
DOC: [FEATURE] Documentation rework for possible PR See merge request ndk/ndk-fpga!73
2 parents d2c22dc + 83b34be commit ea2302f

File tree

14 files changed

+301
-86
lines changed

14 files changed

+301
-86
lines changed

‎.github/workflows/doc.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ jobs:
1616
- name: Setup and build
1717
run: |
1818
sudo apt-get install python3-pip
19-
pip3 install sphinx sphinx-vhdl sphinx_rtd_theme GitPython
19+
pip3 install sphinx sphinx-vhdl sphinx_rtd_theme piccolo_theme GitPython
2020
mkdir public
2121
mkdir public/html
2222
cp doc/source/index.html public/html/

‎.gitlab-ci.yml

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,23 @@ variables:
77
GIT_SUBMODULE_STRATEGY: recursive
88

99
include:
10-
- local: 'tests/ci/check.gitlab-ci.yaml'
10+
- local: "tests/ci/check.gitlab-ci.yaml"
1111

1212
pages:
1313
stage: deploy
1414
image: python:3.9-alpine
1515
script:
16-
- apk add git
17-
- pip install -U GitPython
18-
- pip install -U sphinx
19-
- pip install -U sphinx-rtd-theme
20-
- pip install -U sphinx-vhdl
21-
- echo "Hotfix detached head, causing trouble in GitPython:"
22-
- git checkout $CI_COMMIT_BRANCH
23-
- git status
24-
- sphinx-build -b html doc/source/ public
16+
- apk add git
17+
- pip install -U GitPython
18+
- pip install -U sphinx
19+
- pip install -U piccolo_theme
20+
- pip install -U sphinx-vhdl
21+
- echo "Hotfix detached head, causing trouble in GitPython:"
22+
- git checkout $CI_COMMIT_BRANCH
23+
- git status
24+
- sphinx-build -b html doc/source/ public
2525
artifacts:
2626
paths:
27-
- public
27+
- public
2828
only:
29-
- devel
29+
- devel

‎CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

88
## [Unreleased]
9+
- Improve documentation
10+
- Improve documentation looks
911

1012
## [0.7.2] - 2024-10-17
1113

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ First, you need to install a few Python packages:
6060
$ pip3 install --user GitPython
6161
$ pip3 install --user sphinx
6262
$ pip3 install --user sphinx-vhdl
63-
$ pip3 install --user sphinx_rtd_theme
63+
$ pip3 install --user piccolo_theme
6464
```
6565

6666
Then the documentation is generated simply by issuing these two commands:

‎doc/source/_templates/layout.html

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
{% extends "basic/layout.html" %} {%- block body_tag %}
2+
<body
3+
data-dark_mode_code_blocks="{{ 'true' if theme_dark_mode_code_blocks else 'false' }}"
4+
>
5+
{% endblock %} {%- block header %}
6+
7+
<div id="top_nav">
8+
{% if theme_banner_text and theme_banner_text != 'false' %} {% include
9+
"./components/notification_banner.html" %} {% endif %}
10+
11+
<nav>
12+
{% if logo_url %} {% set nav_title = '<img
13+
src="' + logo_url + '"
14+
/>' %} {% else %} {% set nav_title = shorttitle %} {% endif %}
15+
16+
<p id="toggle_sidebar">
17+
<a href="#" title="Toggle sidebar">|||</a>
18+
</p>
19+
<h1>
20+
<a href="{{ pathto(root_doc)|e }}" title="Go to homepage"
21+
>{{ nav_title }}</a
22+
>
23+
</h1>
24+
25+
{%- if theme_source_url %} {% include
26+
"./components/source_link.html" %} {% endif %} {% include
27+
"./components/dark_mode_toggle.html" %} {%- if pagename != "search"
28+
%}
29+
<p class="mobile_search_link">
30+
<a href="{{ pathto('search') }}" title="Search">
31+
<svg
32+
xmlns="http://www.w3.org/2000/svg"
33+
viewBox="0 0 65 64"
34+
fill-rule="evenodd"
35+
stroke-linejoin="round"
36+
stroke-miterlimit="2"
37+
>
38+
<path
39+
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"
40+
fill="#fff"
41+
/>
42+
</svg>
43+
</a>
44+
</p>
45+
{% endif %}
46+
47+
<div class="searchbox_wrapper">
48+
{% include "basic/searchbox.html" %}
49+
</div>
50+
</nav>
51+
</div>
52+
{% endblock %} {%- block sidebar1 %} {{ sidebar() }} {%- block sidebarlogo
53+
%}{% endblock %} {% endblock %} {%- block sidebar2 %} {% if display_toc %}
54+
<div id="show_right_sidebar">
55+
<p>
56+
<a class="toggle_right_sidebar" href="#"
57+
><span class="icon">&lt;</span><span>Page contents</span></a
58+
>
59+
</p>
60+
</div>
61+
62+
<div id="right_sidebar">
63+
<p>
64+
<a class="toggle_right_sidebar" href="#"
65+
><span class="icon">&gt;</span><span>Page contents:</span></a
66+
>
67+
</p>
68+
<div class="page_toc">{{ toc }}</div>
69+
</div>
70+
{% endif %} {% endblock %} {%- block relbar1 %}{% endblock %} {%- block
71+
scripts %} {{- script() }}
72+
<script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
73+
<script src="{{ pathto('_static/js/petite-vue.js', 1) }}"></script>
74+
{%- endblock %} {%- block relbar2 %}
75+
<div class="button_nav_wrapper">
76+
<div class="button_nav">
77+
<div class="left">
78+
{% if prev %}
79+
<a href="{{ prev.link }}">
80+
<span class="icon">&lt;</span
81+
><span>{{ prev.title }}</span></a
82+
>
83+
{% endif %}
84+
</div>
85+
86+
<div class="right">
87+
{% if next %}
88+
<a href="{{ next.link }}"
89+
><span>{{ next.title }}</span
90+
><span class="icon">&gt;</span></a
91+
>
92+
{% endif %}
93+
</div>
94+
</div>
95+
</div>
96+
{% endblock %} {%- block footer %} {{ super() }}
97+
<div
98+
style="
99+
box-sizing: border-box;
100+
padding-top: 0.2rem;
101+
font-size: 0.7rem;
102+
text-align: center;
103+
color: var(--faintFontColor);
104+
"
105+
>
106+
{{ version }}
107+
</div>
108+
109+
<p id="theme_credit">
110+
{% if theme_show_theme_credit %}Styled using the
111+
<a href="https://github.com/piccolo-orm/piccolo_theme">Piccolo Theme</a
112+
>{% endif %}
113+
</p>
114+
{%- endblock %}
115+
</body>

‎doc/source/base.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Basic Tools
22
===========
33

44
This chapter describes the basic components such as FIFOs, RAMs, multiplexers, encoders, decoders, etc.
5-
The basic components are typically located in the ``comp/base/`` directory in the OFM repository.
5+
The basic components are typically located in the ``comp/base/`` directory in the NDK-FPGA repository.
66

77
.. toctree::
88
:maxdepth: 1
@@ -12,6 +12,5 @@ The basic components are typically located in the ``comp/base/`` directory in th
1212
memory
1313
fifo
1414
dsp
15-
shift
1615
logic
1716
misc

‎doc/source/conf.py

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@
1818

1919
# -- Project information -----------------------------------------------------
2020

21-
project = 'NDK-FPGA Docs'
21+
project = 'NDK-FPGA'
2222
copyright = str(current_year) + ', CESNET z.s.p.o.'
2323
author = 'CESNET TMC'
24-
version = 'Git branch: ' + str(git_branch) + ', <br> Git hash: ' + str(git_sha_short)
24+
version = 'Git branch: ' + str(git_branch) + '<br>Git hash: ' + str(git_sha_short)
2525

2626
# -- General configuration ---------------------------------------------------
2727

@@ -30,8 +30,9 @@
3030
# ones.
3131
extensions = [
3232
"ndk-fpga",
33-
"sphinx_rtd_theme",
34-
"sphinxvhdl.vhdl"
33+
"piccolo_theme",
34+
"sphinxvhdl.vhdl",
35+
"sphinx.ext.autosectionlabel"
3536
]
3637

3738
vhdl_autodoc_source_path = (Path(__file__).parent.parent.parent).resolve()
@@ -50,18 +51,16 @@
5051
# The theme to use for HTML and HTML Help pages. See the documentation for
5152
# a list of builtin themes.
5253
#
53-
html_theme = "sphinx_rtd_theme"
54+
html_theme = 'piccolo_theme'
5455
html_theme_options = {
55-
'collapse_navigation': True,
56-
'sticky_navigation': True,
57-
'navigation_depth': 4,
58-
'includehidden': True,
59-
'display_version': True,
56+
"globaltoc_maxdepth": 4,
57+
"banner_hiding": "permanent",
58+
"show_theme_credit": False,
6059
}
6160

61+
html_logo = "img/ndk_fpga_logo_simple.png"
62+
6263
# Add any paths that contain custom static files (such as style sheets) here,
6364
# relative to this directory. They are copied after the builtin static files,
6465
# so a file named "default.css" will overwrite the builtin "default.css".
6566
html_static_path = ['_static']
66-
67-
html_style = 'css/theme_overrides.css'

‎doc/source/fifo.rst

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,17 @@ FIFO components
66
Dual clock (asynchronous) FIFOs
77
-------------------------------
88

9-
**ASFIFO** - Behavioral dual clock FIFO implementation based on LUTMEMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use ASFIFOX!``
9+
**ASFIFO** - Behavioral dual clock FIFO implementation, based on LUTMEMs and optimized for Xilinx only. Includes status signal.
1010

11-
**ASFIFO_BRAM** - Behavioral dual clock FIFO implementation based on BRAMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use ASFIFOX!``
11+
.. warning::
12+
.. deprecated:: 0.7.0
13+
This component is obsolete and is a candidate for removal, use **ASFIFOX** instead.
14+
15+
**ASFIFO_BRAM** - Behavioral dual clock FIFO implementation, based on BRAMs and optimized for Xilinx only. Includes status signal.
16+
17+
.. warning::
18+
.. deprecated:: 0.7.0
19+
This component is obsolete and is a candidate for removal, use **ASFIFOX** instead.
1220

1321
**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.
1422

@@ -34,13 +42,25 @@ Detailed :ref:`documentation can be found here<asfifox>`.
3442
Single clock FIFOs
3543
------------------
3644

37-
**FIFO** - Behavioral FIFO implementation based on LUTMEMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use FIFOX!``
45+
**FIFO** - Behavioral FIFO implementation, based on LUTMEMs and optimized for Xilinx only. Includes status signal.
46+
47+
.. warning::
48+
.. deprecated:: 0.7.0
49+
This component is obsolete and is a candidate for removal, use **FIFOX** instead.
3850

39-
**FIFO_BRAM** - Behavioral FIFO implementation based on BRAMs and optimized for Xilinx only. Include status signal. ``OBSOLETE, use FIFOX!``
51+
**FIFO_BRAM** - Behavioral FIFO implementation, based on BRAMs and optimized for Xilinx only. Includes status signal.
52+
53+
.. warning::
54+
.. deprecated:: 0.7.0
55+
This component is obsolete and is a candidate for removal, use **FIFOX** instead.
4056

4157
**FIFO_BRAM_XILINX** - Structural implementation of FIFO based on Xilinx specific BRAM FIFO primitives (no extra logic). Include almost full and almost empty signal.
4258

43-
**FIFO_N1** - Behavioral implementation of FIFO with multiple write ports, it based on LUTMEMs and optimized for Xilinx only. ``OBSOLETE, use FIFOX_MULTI!``
59+
**FIFO_N1** - Behavioral implementation of FIFO with multiple write ports, it is based on LUTMEMs and optimized for Xilinx only.
60+
61+
.. warning::
62+
.. deprecated:: 0.7.0
63+
This component is obsolete and is a candidate for removal, use **FIFOX** instead.
4464

4565
**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).
4666
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
5070
**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).
5171
The memory type is selected automatically.
5272

53-
**SH_FIFO** - Behavioral FIFO implementation based on shift-registers in LUT slices and optimized for Xilinx only. ``OBSOLETE, use FIFOX!``
73+
**SH_FIFO** - Behavioral FIFO implementation, based on shift-registers in LUT slices and optimized for Xilinx only.
74+
75+
.. warning::
76+
.. deprecated:: 0.7.0
77+
This component is obsolete and is a candidate for removal, use **FIFOX** instead.
5478

5579
.. toctree::
5680
:maxdepth: 1

‎doc/source/img/ndk_fpga_logo.png

35.4 KB
Loading

0 commit comments

Comments
 (0)