mirror of
https://github.com/YosysHQ/yosys
synced 2025-11-04 05:19:11 +00:00
bb8c72a9d7
Add comments in setup-build-env/action.yml for where to document prereqs (and the separation between build/run and test). Add some initial (very basic) text for `test_suites.rst`, listing prereqs and how to run the tests (with subsections for the different optional tests, which is currently docs, functional and unit). Add sphinx-inline-tabs, use it for tidying up prereq instructions based on OS/platform (mostly helpful in the test suites doc where there are multiple sections split by OS). Also fixes some single backticks that should be double backtick.
131 lines
4.1 KiB
Python
131 lines
4.1 KiB
Python
#!/usr/bin/env python3
|
|
from pathlib import Path
|
|
import sys
|
|
import os
|
|
|
|
project = 'YosysHQ Yosys'
|
|
author = 'YosysHQ GmbH'
|
|
copyright ='2025 YosysHQ GmbH'
|
|
yosys_ver = "0.58"
|
|
|
|
# select HTML theme
|
|
html_theme = 'furo-ys'
|
|
html_css_files = ['custom.css']
|
|
html_theme_options: dict[str] = {
|
|
"source_repository": "https://github.com/YosysHQ/yosys/",
|
|
"source_branch": "main",
|
|
"source_directory": "docs/source/",
|
|
}
|
|
html_context: dict[str] = {}
|
|
|
|
# try to fix the readthedocs detection
|
|
if os.getenv("READTHEDOCS"):
|
|
html_context.update({
|
|
"READTHEDOCS": True,
|
|
"display_github": True,
|
|
"github_user": "YosysHQ",
|
|
"github_repo": "yosys",
|
|
"slug": "yosys",
|
|
})
|
|
|
|
# override source_branch if not main
|
|
git_slug = os.getenv("READTHEDOCS_VERSION_NAME")
|
|
if git_slug not in [None, "latest", "stable"]:
|
|
html_theme_options["source_branch"] = git_slug
|
|
|
|
# edit only works on branches, not tags
|
|
if os.getenv("READTHEDOCS_VERSION_TYPE", "branch") != "branch":
|
|
html_theme_options["top_of_page_buttons"] = ["view"]
|
|
|
|
# These folders are copied to the documentation's HTML output
|
|
html_static_path = ['_static', "_images"]
|
|
|
|
# default to no highlight
|
|
highlight_language = 'none'
|
|
|
|
# default single quotes to attempt auto reference, or fallback to yoscrypt
|
|
default_role = 'autoref'
|
|
rst_prolog = """
|
|
.. role:: yoscrypt(code)
|
|
:language: yoscrypt
|
|
"""
|
|
|
|
extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex', 'sphinx_inline_tabs']
|
|
|
|
if os.getenv("READTHEDOCS"):
|
|
# Use rtds_action if we are building on read the docs and have a github token env var
|
|
if os.getenv("GITHUB_TOKEN"):
|
|
extensions += ['rtds_action']
|
|
rtds_action_github_repo = "YosysHQ/yosys"
|
|
rtds_action_path = "."
|
|
rtds_action_artifact_prefix = "cmd-ref-"
|
|
rtds_action_github_token = os.environ["GITHUB_TOKEN"]
|
|
else:
|
|
# We're on read the docs but have no github token, this is probably a PR preview build
|
|
html_theme_options["announcement"] = 'Missing content? Check <a class="reference internal" href="https://tyrtd--2.org.readthedocs.build/en/2/appendix/building_docs.html#pr-previews-and-limitations">PR preview limitations</a>.'
|
|
html_theme_options["light_css_variables"]["color-announcement-background"] = "var(--color-admonition-title-background--caution)"
|
|
html_theme_options["light_css_variables"]["color-announcement-text"] = "var(--color-content-foreground)"
|
|
|
|
# Ensure that autosectionlabel will produce unique names
|
|
autosectionlabel_prefix_document = True
|
|
|
|
# include todos for previews
|
|
extensions.append('sphinx.ext.todo')
|
|
|
|
# set version
|
|
if os.getenv("READTHEDOCS"):
|
|
rtds_version = os.getenv("READTHEDOCS_VERSION")
|
|
if rtds_version == "latest":
|
|
release = yosys_ver + "-dev"
|
|
todo_include_todos = False
|
|
elif rtds_version.startswith("docs"):
|
|
release = rtds_version
|
|
todo_include_todos = True
|
|
else:
|
|
release = yosys_ver
|
|
todo_include_todos = False
|
|
elif os.getenv("YOSYS_DOCS_RELEASE") is not None:
|
|
release = yosys_ver
|
|
todo_include_todos = False
|
|
else:
|
|
release = yosys_ver
|
|
todo_include_todos = True
|
|
|
|
# assign figure numbers
|
|
numfig = True
|
|
|
|
bibtex_bibfiles = ['literature.bib']
|
|
latex_elements = {
|
|
'releasename': 'Version',
|
|
'preamble': r'''
|
|
\pdfinfoomitdate 1
|
|
\pdfsuppressptexinfo 1
|
|
\pdftrailerid{}
|
|
\usepackage{lmodern}
|
|
\usepackage{comment}
|
|
|
|
'''
|
|
}
|
|
|
|
# custom cmd-ref parsing/linking
|
|
sys.path += [os.path.dirname(__file__) + "/../"]
|
|
extensions.append('util.custom_directives')
|
|
|
|
# use autodocs
|
|
extensions.append('sphinx.ext.autodoc')
|
|
extensions.append('util.cell_documenter')
|
|
cells_json = Path(__file__).parent / 'generated' / 'cells.json'
|
|
extensions.append('util.cmd_documenter')
|
|
cmds_json = Path(__file__).parent / 'generated' / 'cmds.json'
|
|
|
|
from sphinx.application import Sphinx
|
|
def setup(app: Sphinx) -> None:
|
|
from util.RtlilLexer import RtlilLexer
|
|
app.add_lexer("RTLIL", RtlilLexer)
|
|
|
|
try:
|
|
from furo_ys.lexers.YoscryptLexer import YoscryptLexer
|
|
app.add_lexer("yoscrypt", YoscryptLexer)
|
|
except ModuleNotFoundError:
|
|
from pygments.lexers.special import TextLexer
|
|
app.add_lexer("yoscrypt", TextLexer)
|