From d2dc70bb6a560d5aa9df83c3c381843105bcd9ba Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Sun, 13 Feb 2022 19:04:17 +0100 Subject: [PATCH] docs: add logo and favicon; use '_static' Signed-off-by: Unai Martinez-Corral --- docs/_static/favicon.svg | 1 + .../images/arty-usb-ethernet.png | Bin docs/{ => _static}/images/arty.png | Bin docs/{ => _static}/images/basys3-usb.png | Bin docs/{ => _static}/images/basys3.png | Bin .../images/counter-example-arty.gif | Bin .../images/counter-example-basys3.gif | Bin .../images/counter-example-zyboz7-clken.gif | Bin .../images/counter-example-zyboz7-reverse.gif | Bin .../images/counter-example-zyboz7.gif | Bin docs/{ => _static}/images/ethernet-cable.png | Bin .../images/linux-example-arty.jpg | Bin .../images/linux-example-console.gif | Bin .../images/litex-picorv32-console.gif | Bin .../images/picosoc-example-basys3.gif | Bin docs/{ => _static}/images/pwm.gif | Bin .../images/tftp-server-status.png | Bin docs/{ => _static}/images/timer.gif | Bin .../images/usb-a-to-micro-b-cable.png | Bin docs/{ => _static}/images/zyboz7-jmp.png | Bin docs/{ => _static}/images/zyboz7-sdcard.png | Bin docs/{ => _static}/images/zyboz7-usb.png | Bin docs/_static/logo.svg | 66 ++++++++++++++++++ docs/collect_readmes.py | 2 +- docs/conf.py | 33 ++++----- docs/requirements.txt | 2 +- docs/running-examples.rst | 12 ++-- 27 files changed, 92 insertions(+), 24 deletions(-) create mode 100644 docs/_static/favicon.svg rename docs/{ => _static}/images/arty-usb-ethernet.png (100%) rename docs/{ => _static}/images/arty.png (100%) rename docs/{ => _static}/images/basys3-usb.png (100%) rename docs/{ => _static}/images/basys3.png (100%) rename docs/{ => _static}/images/counter-example-arty.gif (100%) rename docs/{ => _static}/images/counter-example-basys3.gif (100%) rename docs/{ => _static}/images/counter-example-zyboz7-clken.gif (100%) rename docs/{ => _static}/images/counter-example-zyboz7-reverse.gif (100%) rename docs/{ => _static}/images/counter-example-zyboz7.gif (100%) rename docs/{ => _static}/images/ethernet-cable.png (100%) rename docs/{ => _static}/images/linux-example-arty.jpg (100%) rename docs/{ => _static}/images/linux-example-console.gif (100%) rename docs/{ => _static}/images/litex-picorv32-console.gif (100%) rename docs/{ => _static}/images/picosoc-example-basys3.gif (100%) rename docs/{ => _static}/images/pwm.gif (100%) rename docs/{ => _static}/images/tftp-server-status.png (100%) rename docs/{ => _static}/images/timer.gif (100%) rename docs/{ => _static}/images/usb-a-to-micro-b-cable.png (100%) rename docs/{ => _static}/images/zyboz7-jmp.png (100%) rename docs/{ => _static}/images/zyboz7-sdcard.png (100%) rename docs/{ => _static}/images/zyboz7-usb.png (100%) create mode 100644 docs/_static/logo.svg diff --git a/docs/_static/favicon.svg b/docs/_static/favicon.svg new file mode 100644 index 0000000..5535f19 --- /dev/null +++ b/docs/_static/favicon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/arty-usb-ethernet.png b/docs/_static/images/arty-usb-ethernet.png similarity index 100% rename from docs/images/arty-usb-ethernet.png rename to docs/_static/images/arty-usb-ethernet.png diff --git a/docs/images/arty.png b/docs/_static/images/arty.png similarity index 100% rename from docs/images/arty.png rename to docs/_static/images/arty.png diff --git a/docs/images/basys3-usb.png b/docs/_static/images/basys3-usb.png similarity index 100% rename from docs/images/basys3-usb.png rename to docs/_static/images/basys3-usb.png diff --git a/docs/images/basys3.png b/docs/_static/images/basys3.png similarity index 100% rename from docs/images/basys3.png rename to docs/_static/images/basys3.png diff --git a/docs/images/counter-example-arty.gif b/docs/_static/images/counter-example-arty.gif similarity index 100% rename from docs/images/counter-example-arty.gif rename to docs/_static/images/counter-example-arty.gif diff --git a/docs/images/counter-example-basys3.gif b/docs/_static/images/counter-example-basys3.gif similarity index 100% rename from docs/images/counter-example-basys3.gif rename to docs/_static/images/counter-example-basys3.gif diff --git a/docs/images/counter-example-zyboz7-clken.gif b/docs/_static/images/counter-example-zyboz7-clken.gif similarity index 100% rename from docs/images/counter-example-zyboz7-clken.gif rename to docs/_static/images/counter-example-zyboz7-clken.gif diff --git a/docs/images/counter-example-zyboz7-reverse.gif b/docs/_static/images/counter-example-zyboz7-reverse.gif similarity index 100% rename from docs/images/counter-example-zyboz7-reverse.gif rename to docs/_static/images/counter-example-zyboz7-reverse.gif diff --git a/docs/images/counter-example-zyboz7.gif b/docs/_static/images/counter-example-zyboz7.gif similarity index 100% rename from docs/images/counter-example-zyboz7.gif rename to docs/_static/images/counter-example-zyboz7.gif diff --git a/docs/images/ethernet-cable.png b/docs/_static/images/ethernet-cable.png similarity index 100% rename from docs/images/ethernet-cable.png rename to docs/_static/images/ethernet-cable.png diff --git a/docs/images/linux-example-arty.jpg b/docs/_static/images/linux-example-arty.jpg similarity index 100% rename from docs/images/linux-example-arty.jpg rename to docs/_static/images/linux-example-arty.jpg diff --git a/docs/images/linux-example-console.gif b/docs/_static/images/linux-example-console.gif similarity index 100% rename from docs/images/linux-example-console.gif rename to docs/_static/images/linux-example-console.gif diff --git a/docs/images/litex-picorv32-console.gif b/docs/_static/images/litex-picorv32-console.gif similarity index 100% rename from docs/images/litex-picorv32-console.gif rename to docs/_static/images/litex-picorv32-console.gif diff --git a/docs/images/picosoc-example-basys3.gif b/docs/_static/images/picosoc-example-basys3.gif similarity index 100% rename from docs/images/picosoc-example-basys3.gif rename to docs/_static/images/picosoc-example-basys3.gif diff --git a/docs/images/pwm.gif b/docs/_static/images/pwm.gif similarity index 100% rename from docs/images/pwm.gif rename to docs/_static/images/pwm.gif diff --git a/docs/images/tftp-server-status.png b/docs/_static/images/tftp-server-status.png similarity index 100% rename from docs/images/tftp-server-status.png rename to docs/_static/images/tftp-server-status.png diff --git a/docs/images/timer.gif b/docs/_static/images/timer.gif similarity index 100% rename from docs/images/timer.gif rename to docs/_static/images/timer.gif diff --git a/docs/images/usb-a-to-micro-b-cable.png b/docs/_static/images/usb-a-to-micro-b-cable.png similarity index 100% rename from docs/images/usb-a-to-micro-b-cable.png rename to docs/_static/images/usb-a-to-micro-b-cable.png diff --git a/docs/images/zyboz7-jmp.png b/docs/_static/images/zyboz7-jmp.png similarity index 100% rename from docs/images/zyboz7-jmp.png rename to docs/_static/images/zyboz7-jmp.png diff --git a/docs/images/zyboz7-sdcard.png b/docs/_static/images/zyboz7-sdcard.png similarity index 100% rename from docs/images/zyboz7-sdcard.png rename to docs/_static/images/zyboz7-sdcard.png diff --git a/docs/images/zyboz7-usb.png b/docs/_static/images/zyboz7-usb.png similarity index 100% rename from docs/images/zyboz7-usb.png rename to docs/_static/images/zyboz7-usb.png diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg new file mode 100644 index 0000000..29b511d --- /dev/null +++ b/docs/_static/logo.svg @@ -0,0 +1,66 @@ + + + + + + + + + + + + + diff --git a/docs/collect_readmes.py b/docs/collect_readmes.py index d84daac..54fe736 100644 --- a/docs/collect_readmes.py +++ b/docs/collect_readmes.py @@ -102,7 +102,7 @@ def handle_img(block): ret = {} ret['type'] = 'image' - ret['uri'] = os.path.join(*block['uri'].split('/')[3:]) + ret['uri'] = '_static/' + os.path.join(*block['uri'].split('/')[3:]) ret['align'] = block.get('align', 'center') ret['width'] = block.get('width', '100%') diff --git a/docs/conf.py b/docs/conf.py index aca15b5..00ca661 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,16 +29,17 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -import os -import sys +from os import path as os_path, scandir as os_scandir +from sys import path as sys_path +from pathlib import Path -sys.path.insert(0, os.path.abspath('.')) +sys_path.insert(0, os_path.abspath('.')) # -- Project information ----------------------------------------------------- -project = u'F4PGA examples' -authors = u'F4PGA Authors' -copyright = authors + u', 2020 - 2022' +project = 'F4PGA examples' +authors = 'F4PGA Authors' +copyright = f'{authors}, 2020 - 2022' # -- General configuration --------------------------------------------------- @@ -60,16 +61,13 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# - html_show_sourcelink = True html_theme = 'sphinx_symbiflow_theme' html_theme_options = { - 'github_url' : 'https://github.com/chipsalliance/F4PGA-examples', + 'repo_name': 'chipsalliance/f4pga-examples', + 'github_url' : 'https://github.com/chipsalliance/f4pga-examples', 'globaltoc_collapse': True, 'color_primary': 'indigo', 'color_accent': 'blue', @@ -78,24 +76,27 @@ html_theme_options = { # 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'] + +html_logo = str(Path(html_static_path[0]) / 'logo.svg') +html_favicon = str(Path(html_static_path[0]) / 'favicon.svg') # -- Collect READMEs from examples -------------------------------------------- from collect_readmes import full_name_lut, families, fill_context jinja_contexts = {} -top_dir = os.path.join(os.path.dirname(__file__), '..') +top_dir = os_path.join(os_path.dirname(__file__), '..') for family in families: - examples = os.scandir(os.path.join(top_dir, family)) + examples = os_scandir(os_path.join(top_dir, family)) for example in examples: if example.is_dir(): # get README - path = os.path.join(top_dir, family, example, 'README.rst') + path = os_path.join(top_dir, family, example, 'README.rst') # skip if file does not exist - if not os.path.isfile(path): + if not os_path.isfile(path): continue with open(path) as f: diff --git a/docs/requirements.txt b/docs/requirements.txt index 7743ac3..776e935 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ sphinx -docutils==0.17 +docutils git+https://github.com/SymbiFlow/sphinx_symbiflow_theme.git@chips#egg=sphinx-symbiflow-theme sphinx-tabs sphinx-jinja diff --git a/docs/running-examples.rst b/docs/running-examples.rst index eeb6e36..9ab4ff5 100644 --- a/docs/running-examples.rst +++ b/docs/running-examples.rst @@ -14,7 +14,7 @@ Arty board #. Connect the board to your computer using the Ethernet cable (only if you want to test the LiteX Linux Example) -.. image:: images/arty-usb-ethernet.png +.. image:: _static/images/arty-usb-ethernet.png :width: 49% :align: center @@ -23,7 +23,7 @@ Basys 3 board Connect the Basys3 Board to your computer using the USB cable: -.. image:: images/basys3-usb.png +.. image:: _static/images/basys3-usb.png :width: 49% :align: center @@ -32,13 +32,13 @@ Zybo-Z7 board Connect the Zybo-Z7 Board to your computer using the USB cable: -.. image:: images/zyboz7-usb.png +.. image:: _static/images/zyboz7-usb.png :width: 49% :align: center Insert the SD card in the dedicated slot: -.. image:: images/zyboz7-sdcard.png +.. image:: _static/images/zyboz7-sdcard.png :width: 49% :align: center @@ -201,7 +201,7 @@ Load bitstreams from U-boot Make sure to have :ref:`prepared the SD correctly`. #. With the SD card inserted in the PC, copy the bitstream in the boot directory: - + .. code-block:: bash cp .bit /path/to/mountpoint/boot @@ -209,7 +209,7 @@ Make sure to have :ref:`prepared the SD correctly`. #. Set the jumper J5 to SD. - .. image:: images/zyboz7-jmp.png + .. image:: _static/images/zyboz7-jmp.png :width: 49% :align: center