Merge pull request #11 from mithro/main Add sphinx / readthedocs output generation
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..902f9e6 --- /dev/null +++ b/.gitignore
@@ -0,0 +1,141 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + + +**/timing/*.lib
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..ce36e0c --- /dev/null +++ b/docs/Makefile
@@ -0,0 +1,40 @@ +# -*- coding: utf-8 -*- +# Copyright 2022 Google LLC +# +# 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)/..) + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD = sphinx-build +SPHINXAUTOBUILD = sphinx-autobuild +SPHINXPROJ = open_source_pdks +SOURCEDIR = $(DOCS_DIR) +BUILDDIR = $(DOCS_DIR)/_build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0f43d62 --- /dev/null +++ b/docs/conf.py
@@ -0,0 +1,182 @@ +# -*- coding: utf-8 -*- +# Copyright 2022 Google LLC +# +# 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 = 'Google maintained open source PDK' +copyright = '2022, Google LLC' +author = 'Google LLC' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '' + +# -- General configuration --------------------------------------------------- + +# 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', +] + +# 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": "open-source-pdks", # Repo name + "github_version": "main", # Version + "conf_py_path": "/docs/", + } +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 = [] + +# 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', + 'venv', + 'Thumbs.db', + '.DS_Store', +] + +# 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" + +#html_logo = "_static/open-source-pdks-logo-top.png" + +# 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. +# https://sphinx-symbiflow-theme.readthedocs.io/en/latest/customization.html +html_theme_options = { + 'nav_title': 'Google maintained open source PDKs', + + 'color_primary': 'indigo', + 'color_accent': 'blue', + + # Set the repo location to get a badge with stats + 'github_url': 'https://github.com/google/open-source-pdks', + 'repo_name': 'open-source-pdks', + 'repo_type': 'github', + + 'globaltoc_depth': 0, + 'globaltoc_collapse': 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'] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('open-source-pdks', 'Google maintained open source PDKs Documentation', + [author], 1) +]
diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..966f7b2 --- /dev/null +++ b/docs/index.rst
@@ -0,0 +1,25 @@ +.. toctree:: + :hidden: + + versioning + naming + + contributing + code-of-conduct + +Google maintained open source PDKs +================================== + +This documentation includes information common to Google maintained open source PDKs. + +It should be included into the documentation shipped with those PDKs. + +.. include:: ../README.rst + +Resources +========= + +The rendered documentation can be found at https://open-source-pdks.rtfd.io + +The source of the documentation can be found at https://github.com/google/opens-source-pdks +
diff --git a/docs/naming.rst b/docs/naming.rst new file mode 100644 index 0000000..34c9270 --- /dev/null +++ b/docs/naming.rst
@@ -0,0 +1,45 @@ +Naming +====== + +Library Naming +-------------- + +Libraries in the Google open source PDKs are named using the following scheme; + + :lib_process:`<Process name>` _ :lib_src:`<Library Source Abbreviation>` _ :lib_type:`<Library Type Abbreviation>` [_ :lib_name:`<Library Name>`] + +All sections are **lower case** and separated by an **underscore**. All sections must start with an alpha character (they must not start with a number). + +The sections are; + +- The :lib_process:`Process name` in is the name of the process technology. + +- The :lib_src:`Library Source Abbreviations` is a short abbreviation for who created and is responsible for the library. The table below shows the current list of :lib_src:`Library Source Abbreviations`; + + +----------------------------+----------------------------------------+ + | Library Source | :lib_src:`Library Source Abbreviation` | + +============================+========================================+ + | Technology's foundry | :lib_src:`fd` | + +----------------------------+----------------------------------------+ + | Efabless | :lib_src:`ef` | + +----------------------------+----------------------------------------+ + | Oklahoma State University | :lib_src:`osu` | + +----------------------------+----------------------------------------+ + +- The :lib_type:`Library Type Abbreviation` is a short two letter abbreviation for the type of content found in the library. The table below shows the current list of :lib_type:`Library Type Abbreviations`; + + +--------------------------------+---------------------------------------+ + | Library Type | :lib_type:`Library Type Abbreviation` | + +================================+=======================================+ + | Primitive Cells | :lib_type:`pr` | + +--------------------------------+---------------------------------------+ + | Digital Standard Cells | :lib_type:`sc` | + +--------------------------------+---------------------------------------+ + | Build Space (Flash, SRAM, etc) | :lib_type:`sp` | + +--------------------------------+---------------------------------------+ + | IO and Periphery | :lib_type:`io` | + +--------------------------------+---------------------------------------+ + | Miscellaneous | :lib_type:`xx` | + +--------------------------------+---------------------------------------+ + +- The :lib_name:`Library Name` is an optional short abbreviated name used when there are multiple libraries of a given type released from a single :lib_src:`library source`. If only one library of a given type is going to ever be released, this can be left out.
diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..e304d5b --- /dev/null +++ b/docs/requirements.txt
@@ -0,0 +1,5 @@ +git+https://github.com/f4pga/sphinx_f4pga_theme#egg=sphinx-symbiflow-theme + +docutils +sphinx +sphinx-autobuild
diff --git a/docs/versioning.rst b/docs/versioning.rst new file mode 100644 index 0000000..8d90ace --- /dev/null +++ b/docs/versioning.rst
@@ -0,0 +1,36 @@ +Versioning Information +====================== + +Version Number Format +--------------------- + +Version numbers for both the PDK and the supplied libraries are fully specified by a 3-digit version number followed by a git commit count and a git commit short hash. + +The 3-digit-number will be tagged in the associated git repository as ``vX.Y.Z`` and the fully specified value can be found by running |git-describe|_ tool inside the correct git repository. + +.. |git-describe| replace:: ``git describe`` +.. _git-describe: https://git-scm.com/docs/git-describe + +The version number is broken down as ``vX.Y.Z-AAA-gHHHHH``; + +* The letter ``v``. + +* ``X`` = The "Milestone Release" Number + + * **0** indicates **"alpha"** level. The IP has **not** undergone full qualification. Parts of the IP **may be immature and untested**. + + * **1** indicates **"beta"** level. The IP has undergone qualification testing but has **not** been hardware verified. + + * **2** indicates **production** level. The IP has passed qualification testing and has been hardware verified. + +* ``Y`` = The "Major Release" Number + +* ``Z`` = The "Minor Release" Number + +* A single hyphen character ``-`` + +* ``AAA`` = The `git commit count <https://git-scm.com/docs/git-describe#_examples>`_ since the version number was tagged. + +* A single hyphen character followed by the letter g ``-g`` + +* ``HHHH`` = A `git commit short hash <https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_short_sha_1>`_ which uniquely identifies a specific git commit inside the associated git repository.