1  import datetime
  2  from sphinx_rtd_theme import get_html_theme_path
  3  
  4  # -- General configuration -----------------------------------------------------
  5  
  6  general_theme = "sphinx_rtd_theme"
  7  
  8  # Documentation theme.
  9  theme_path = get_html_theme_path() + "/" + general_theme
 10  
 11  # Minimal Sphinx version.
 12  needs_sphinx = "5.1.0"
 13  
 14  # Add any extensions here. These could be both Sphinx or custom ones.
 15  extensions = [
 16      "myst_parser",
 17      "sphinx.ext.intersphinx",
 18      "sphinx.ext.todo",
 19      "sphinx.ext.ifconfig",
 20      "sphinx.ext.extlinks",
 21      "sphinx.ext.autodoc",
 22      "sphinx.ext.autosummary",
 23      "sphinxcontrib.mermaid",
 24      "numpydoc",
 25  ]
 26  
 27  # If true, figures, tables and code-blocks are automatically numbered
 28  # if they have a caption.
 29  numfig = True
 30  
 31  # The suffix of source filenames.
 32  source_suffix = {
 33      ".md": "markdown",
 34      ".rst": "restructuredtext",
 35  }
 36  
 37  # The main toctree document.
 38  master_doc = "index"
 39  
 40  # General information about the project.
 41  project = "Coreblocks documentation"
 42  output_filename = "coreblocks-docs"
 43  authors = "Kuźnia Rdzeni"
 44  copyright = authors + ", {}".format(datetime.datetime.now().year)
 45  
 46  # Specify time format. Used in 'Last Updated On:'.
 47  today_fmt = "%H:%M %Y-%m-%d"
 48  
 49  # The name of the Pygments (syntax highlighting) style to use.
 50  # This affects the code blocks. More styles: https://pygments.org/styles/
 51  pygments_style = "sphinx"
 52  
 53  # -- HTML output ---------------------------------------------------------------
 54  
 55  # The theme to be used for HTML documentation.
 56  html_theme = general_theme
 57  
 58  # The title to be shown at all html documents.
 59  # Default is "<project> v<release> documentation".
 60  html_title = project
 61  
 62  # A shorter title to appear at the navigation bar. Default is html_title.
 63  html_short_title = "Coreblocks"
 64  
 65  # 'Last updated on:' timestamp is inserted at every page bottom,
 66  # using the given strftime format. To disable set it to ''.
 67  html_last_updated_fmt = today_fmt
 68  
 69  # If True show "Created using Sphinx" in the HTML footer.
 70  html_show_sphinx = False
 71  
 72  # Logo of this project.
 73  html_logo = "images/logo-banner.svg"
 74  
 75  # -- Custom filters ------------------------------------------------------------
 76  
 77  
 78  # Exclude some methods from the api documentation
 79  def hide_non_private(app, what, name, obj, skip, options):
 80      if "elaborate" in name:
 81          # skip elaborates
 82          return True
 83      elif "__init__" == name:
 84          # Include __init__ (excluded by default)
 85          return False
 86      else:
 87          # otherwise generate an entry
 88          return None
 89  
 90  
 91  def setup(app):
 92      app.connect("autodoc-skip-member", hide_non_private)
 93  
 94  
 95  # If set to False it doesn't generate summary of class Methods if not
 96  # explicitly described in docsting. This prevents many mostly empty Method
 97  # sections in most classes since 'elaborate' methods are not documented.
 98  numpydoc_show_class_members = False
 99  
100  # Show typehints in the signature
101  autodoc_typehints = "signature"
102  
103  # Display the class signature as a method
104  autodoc_class_signature = "separated"
105  
106  # Auto generate anchors for # - ### headers
107  myst_heading_anchors = 3
108  
109  # Compatibility with Amaranth docstrings
110  rst_prolog = """
111  .. role:: py(code)
112     :language: python
113  """
114  
115  intersphinx_mapping = {
116      "python": ("https://docs.python.org/3", None),
117      "amaranth": ("https://amaranth-lang.org/docs/amaranth/latest/", None),
118  }