Merge remote-tracking branch 'docs/master'
diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..3abb82d --- /dev/null +++ b/.gitmodules
@@ -0,0 +1,3 @@ +[submodule "third_party/make-env"] + path = third_party/make-env + url = git+ssh://github.com/SymbiFlow/make-env.git
diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..19ac2d0 --- /dev/null +++ b/docs/.gitignore
@@ -0,0 +1,2 @@ +env +_build
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c97e401 --- /dev/null +++ b/docs/Makefile
@@ -0,0 +1,97 @@ +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +# The top directory where environment will be created. +DOCS_DIR := $(dir $(lastword $(MAKEFILE_LIST))) +TOP_DIR := $(realpath $(DOCS_DIR)/..) + +# A pip `requirements.txt` file. +# https://pip.pypa.io/en/stable/reference/pip_install/#requirements-file-format +REQUIREMENTS_FILE := $(DOCS_DIR)/requirements.txt + +# A conda `environment.yml` file. +# https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html +ENVIRONMENT_FILE := $(DOCS_DIR)/environment.yml + +$(TOP_DIR)/third_party/make-env/conda.mk: $(TOP_DIR)/.gitmodules + cd $(TOP_DIR); git submodule update --init third_party/make-env + touch $(TOP_DIR)/third_party/make-env/conda.mk + +-include $(TOP_DIR)/third_party/make-env/conda.mk + +SHELL = /bin/bash + +EXP_OPEN := $$(( +EXP_CLOSE := )) +CPU_CORES := $(shell nproc) +CPU_CORES_2 := $(shell echo $(EXP_OPEN) $(CPU_CORES) * 2 $(EXP_CLOSE)) + +SPHINXOPTS = -j $(CPU_CORES_2) +SPHINXBUILD = $(IN_CONDA_ENV) sphinx-build +SPHINXAUTOBUILD = $(IN_CONDA_ENV) sphinx-autobuild +SPHINXPROJ = SkyWaterPDK +SOURCEDIR = $(DOCS_DIR) +BUILDDIR = $(DOCS_DIR)/_build + +# Put it first so that "make" without argument is like "make help". +help: | $(CONDA_ENV_PYTHON) + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# Vim makes a '4913' file for file system checking. Seriously. +livehtml: | $(CONDA_ENV_PYTHON) + @$(SPHINXAUTOBUILD) \ + -b html \ + --delay 5 \ + \ + --ignore \*.swp \ + --ignore \*~ \ + --ignore env \ + --ignore _build \ + --ignore .git \ + --ignore */4913 \ + \ + $(SPHINXOPTS) \ + "$(SOURCEDIR)" \ + "$(BUILDDIR)/html" + +.PHONY: help livehtml Makefile + +# Various automated fixups that can be run +fixup: + # Make sure it is SkyWater + find ../ -type f -name \*.rst -exec sed -i 's/Skywater/SkyWater/gi' \{\} \+ + # Strip trailing space + find ../ -type f -name \*.rst -exec sed -i 's/ \+$$//' \{\} \+ + # Make sure all library names have the :lib: role. + find ../ -type f -name \*.rst -exec sed -i -e'/:name:.*/!s/\(:lib:\)\?`\?\(sky130_[a-z0-9]\+_[a-z0-9]\+\(_[a-z0-9]\+\)\?\)`\?\(\s\|$$\)/:lib:`\2`\4/g' \{\} \+ + +.PHONY: fixup + +echo: | $(CONDA_ENV_PYTHON) + @echo '$(SPHINXBUILD) -M XXXX "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)' + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +.DEFAULT: | $(CONDA_ENV_PYTHON) + @make env + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +clean:: clean-docs + + +clean-docs: + rm -rf _build
diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..b817d54 --- /dev/null +++ b/docs/conf.py
@@ -0,0 +1,419 @@ +# -*- coding: utf-8 -*- +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# 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 docutils +import os +import re +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'SkyWater SKY130 PDK' +copyright = '2020, SkyWater PDK Authors' +author = 'SkyWater PDK Authors' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.githubpages', + 'sphinx.ext.ifconfig', + 'sphinx.ext.mathjax', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinxcontrib_hdl_diagrams', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# Enable github links when not on readthedocs +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +if not on_rtd: + html_context = { + "display_github": True, # Integrate GitHub + "github_user": "google", # Username + "github_repo": "skywater-pdk", # Repo name + "github_version": "master", # Version + "conf_py_path": "/doc/", + } +else: + docs_dir = os.path.abspath(os.path.dirname(__file__)) + print("Docs dir is:", docs_dir) + import subprocess + subprocess.call('git fetch origin --unshallow', cwd=docs_dir, shell=True) + subprocess.check_call('git fetch origin --tags', cwd=docs_dir, shell=True) + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The full version, including alpha/beta/rc tags. +release = re.sub('^v', '', os.popen('git describe ').read().strip()) +# The short X.Y version. +version = release + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + '_build', + 'env', + 'Thumbs.db', + '.DS_Store', + # Files included in other rst files. + 'code-of-conduct.rst', + 'rules/periphery-rules.rst', + 'rules/device-details/*/index.rst', +] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# Prefix each section label with the name of the document it is in, followed by +# a colon. For example, index:Introduction for a section called Introduction +# that appears in document index.rst. Useful for avoiding ambiguity when the +# same section heading appears in different documents. +#autosectionlabel_prefix_document = True + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_symbiflow_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = { + # Specify a list of menu in Header. + # Tuples forms: + # ('Name', 'external url or path of pages in the document', boolean, 'icon name') + # + # Third argument: + # True indicates an external link. + # False indicates path of pages in the document. + # + # Fourth argument: + # Specify the icon name. + # For details see link. + # https://material.io/icons/ + 'header_links': [ + ('Home', 'index', False, 'home'), + ("GitHub", "https://github.com/google/skywater-pdk", True, 'code'), + ("SkyWater", "https://www.skywatertechnology.com/", True, 'link'), + ], + + # Customize css colors. + # For details see link. + # https://getmdl.io/customize/index.html + # + # Values: amber, blue, brown, cyan deep_orange, deep_purple, green, grey, indigo, light_blue, + # light_green, lime, orange, pink, purple, red, teal, yellow(Default: indigo) + 'primary_color': 'light_green', + # Values: Same as primary_color. (Default: pink) + 'accent_color': 'teal', + + # Customize layout. + # For details see link. + # https://getmdl.io/components/index.html#layout-section + 'fixed_drawer': True, + 'fixed_header': True, + 'header_waterfall': True, + 'header_scroll': False, + + # Render title in header. + # Values: True, False (Default: False) + 'show_header_title': False, + # Render title in drawer. + # Values: True, False (Default: True) + 'show_drawer_title': True, + # Render footer. + # Values: True, False (Default: True) + 'show_footer': True, + + # Hide the symbiflow links + 'hide_symbiflow_links': True, + 'license_url' : 'https://www.apache.org/licenses/LICENSE-2.0', +} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'skywater-pdk-doc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + # source start file + master_doc, + # target name + 'skywater-pdk.tex', + # title + 'SkyWater SKY130 PDK Documentation', + # author + author, + # document class + 'manual', + ), +] + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'skywater-pdk', 'SkyWater SKY130 PDK Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + # source start file + master_doc, + # target name + 'skywater-pdk', + # title + 'SkyWater SKY130 PDK Documentation', + # author + author, + # dir menu entry + 'SkyWater SKY130 PDK', + # description + 'Documentation for open source PDK targetting SkyWater SKY130 process node.', + # category + 'Miscellaneous', + ), +] + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# Enable the figures and numbers +numfig = True + +# -- Extension configuration ------------------------------------------------- + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +import re +from docutils.parsers.rst import directives, roles, nodes + +LIB_REGEX = re.compile('sky130_(?P<lib_src>[^_\s]*)_(?P<lib_type>[^_\s]*)(_(?P<lib_name>[^_\s]*))?') +CELL_REGEX = re.compile('sky130_(?P<lib_src>[^_\s]*)_(?P<lib_type>[^_\s]*)(_(?P<lib_name>[^_\s]*))?__(?P<cell_name>[^\s]*)') + +def lib_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + """Library name which gets colorized.""" + m = LIB_REGEX.match(text) + if not m: + msg = inliner.reporter.error("Malformed library name of "+repr(text), line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] + app = inliner.document.settings.env.app + + #lib_process_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + #lib_src_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + #lib_type_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + #lib_name_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + lib_process = 'sky130' + lib_src = m.group('lib_src') + lib_type = m.group('lib_type') + lib_name = m.group('lib_name') + + r = [ + nodes.inline(lib_process, lib_process, classes=['lib-process']), + nodes.inline('_', '_', options=options), + nodes.inline(lib_src, lib_src, classes=['lib-src']), + nodes.inline('_', '_', options=options), + nodes.inline(lib_type, lib_type, classes=['lib-type']), + ] + if lib_name: + r.append(nodes.inline('_', '_', options=options)) + r.append(nodes.inline(lib_name, lib_name, classes=['lib-name'])) + + return r, [] + + +def cell_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + """Cell name which gets colorized.""" + m = CELL_REGEX.match(text) + if not m: + msg = inliner.reporter.error("Malformed cell name of "+repr(text), line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] + app = inliner.document.settings.env.app + + #lib_process_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + #lib_src_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + #lib_type_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + #lib_name_role = roles.role('lib_src', inliner.language, lineno, inliner.reporter) + lib_process = 'sky130' + lib_src = m.group('lib_src') + lib_type = m.group('lib_type') + lib_name = m.group('lib_name') + cell_name = m.group('cell_name') + + r = [ + nodes.inline(lib_process, lib_process, classes=['lib-process']), + nodes.inline('_', '_', options=options), + nodes.inline(lib_src, lib_src, classes=['lib-src']), + nodes.inline('_', '_', options=options), + nodes.inline(lib_type, lib_type, classes=['lib-type']), + ] + if lib_name: + r.append(nodes.inline('_', '_', options=options)) + r.append(nodes.inline(lib_name, lib_name, classes=['lib-name'])) + r.append(nodes.inline('__', '__', options=options)) + r.append(nodes.inline(cell_name, cell_name, classes=['cell-name'])) + + return r, [] + + +def add_role(app, new_role_name): + options = { + 'class': directives.class_option(new_role_name), + } + role = roles.CustomRole(new_role_name, roles.generic_custom_role, options, "") + app.add_role(new_role_name, role) + + +def setup(app): + app.add_css_file('extra.css') + add_role(app, 'cell_name') + add_role(app, 'lib_process') + add_role(app, 'lib_src') + add_role(app, 'lib_type') + add_role(app, 'lib_name') + add_role(app, 'drc_rule') + add_role(app, 'drc_tag') + add_role(app, 'drc_flag') + add_role(app, 'layer') + + app.add_role('lib', lib_role) + app.add_role('cell', cell_role) + app.add_role('model', cell_role)
diff --git a/docs/environment.yml b/docs/environment.yml new file mode 100644 index 0000000..23797fd --- /dev/null +++ b/docs/environment.yml
@@ -0,0 +1,28 @@ +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 +name: skywater-pdk-docs +channels: +- symbiflow +- conda-forge +- defaults +dependencies: +- python=3.8 +- pip +- yosys +- netlistsvg +# Packages installed from PyPI +- pip: + - -r file:requirements.txt
diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..f20b3a6 --- /dev/null +++ b/docs/requirements.txt
@@ -0,0 +1,21 @@ +git+https://github.com/SymbiFlow/sphinx_materialdesign_theme.git#egg=sphinx-symbiflow-theme + +docutils +sphinx +sphinx-autobuild + +# Verilog domain +sphinx-verilog-domain +# Verilog diagrams using Yosys + netlistsvg +sphinxcontrib-hdl-diagrams + +# Module diagrams +git+https://github.com/SymbiFlow/symbolator.git#egg=symbolator + +# pycairo +# vext.gi + +restructuredtext-lint +rstdoc + +tabulate
diff --git a/third_party/make-env b/third_party/make-env new file mode 160000 index 0000000..ea960c7 --- /dev/null +++ b/third_party/make-env
@@ -0,0 +1 @@ +Subproject commit ea960c7821f03d81c4f10dc1e7515a5c4546cf28