docs: Generate README.rst to work around GitHub not rendering `.. include::` in rst files.

This work might look like extensive for just fixing a small issue like
the include rendering, but it will all be heavily reused by the
skywater-pdk scripts that will be released soon.

This commit;
 - Adds Makefile for creating a self contained conda environment under
   `env/conda`

 - Installs required Python dependencies into the environment (which is
   currently just the `rst_include` tool).

 - Has a Makefile to generate `README.rst` from `README.src.rst`

 - Has Travis CI run on repository and check that the `README.rst` file
   has been rebuilt and committed if any of the dependencies have
   change.

Signed-off-by: Tim 'mithro' Ansell <tansell@google.com>

.github/travis/common.sh

@@ -0,0 +1,48 @@
+#!/usr/env false
+#
+# 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
+
+# Some colors, use it like following;
+# echo -e "Hello ${YELLOW}yellow${NC}"
+GRAY=' \033[0;30m'
+RED=' \033[0;31m'
+GREEN=' \033[0;32m'
+YELLOW=' \033[0;33m'
+PURPLE=' \033[0;35m'
+NC='\033[0m' # No Color
+
+SPACER="echo -e ${GRAY} - ${NC}"
+
+export -f travis_nanoseconds
+export -f travis_fold
+export -f travis_time_start
+export -f travis_time_finish
+export -f travis_wait
+export -f travis_jigger
+
+function start_section() {
+        travis_fold start "$1"
+        travis_time_start
+        echo -e "${PURPLE}${1}${NC}: $2${NC}"
+        echo -e "${GRAY}-------------------------------------------------------------------${NC}"
+}
+
+function end_section() {
+        echo -e "${GRAY}-------------------------------------------------------------------${NC}"
+        travis_time_finish
+        travis_fold end "$1"
+}

.github/travis/git-check.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# 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
+
+set -e
+
+source .github/travis/common.sh
+
+# Output any changes in the repository
+# ------------------------------------------------------------------------
+start_section git-status "Current git status"
+
+git diff
+
+$SPACER
+
+git status
+
+end_section git-status
+
+# Check there are not changes in the repository
+# ------------------------------------------------------------------------
+start_section git-check "Checking git repository isn't dirty"
+
+(
+	. "$(git --exec-path)/git-sh-setup"
+
+	require_clean_work_tree "continue" "Please include the changes in your commits."
+)
+
+end_section git-check

.gitignore

@@ -0,0 +1,138 @@
+# 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/

.travis.yml

@@ -0,0 +1,30 @@
+# 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
+
+language: minimal
+
+git:
+  submodules: false
+  depth: false
+
+install:
+ - git describe
+ - make env
+
+script:
+ - source .github/travis/common.sh
+ - rm -f README.rst && make README.rst
+ - .github/travis/git-check.sh

Makefile

@@ -0,0 +1,22 @@
+# 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
+
+include scripts/make/git.mk
+include scripts/make/conda.mk
+
+README.rst: README.src.rst docs/status.rst | $(CONDA_ENV_PYTHON)
+	@rm -f README.rst
+	$(IN_CONDA_ENV) rst_include include --source README.src.rst | sed -e's/|TAG_VERSION|/$(TAG_VERSION)/g' > README.rst

README.src.rst

@@ -41,7 +41,7 @@ The SkyWater Open Source PDK documentation can be found at <https://skywater-pdk
 See both the :ref:`Known Issues` section and the `SkyWater PDK GitHub issue list <https://github.com/google/skywater-pdk/issues>`_ to get more detailed information around currently known issues.
 
 SKY130 Process Node
-===================
+-------------------
 
 The SKY130 is a mature 180nm-130nm hybrid technology originally developed internally by Cypress Semiconductor before being spun out into SkyWater Technology and made accessible to general industry. SkyWater and Google’s collaboration is now making this technology accessible to everyone!
 
@@ -58,19 +58,11 @@ The SKY130 Process node technology stack consists of;
 * HV extended-drain NMOS and PMOS
 
 
-The `SKY130 Process Node`_ has is a extremely flexible offering, including many normally *optional* features as standard (feature like the local interconnect, SONOS functionality, MiM capacitors and more). This provides the designer with a **wide range** of flexibility in design choices.
-
-If your needs extend beyond the standard included functionality in the `SKY130 Process Node`_, please see `Contacting SkyWater`_ as they specializes in enabling production volume of process customization include `the addition of specialized materials like Nb, Ge, V2O5, Carbon Nanotubes <https://www.skywatertechnology.com/technology/>`_. Google and SkyWater continuing to explore new options to be included in the `SkyWater Open Source PDK`_ and `SKY130 Process Node`_ that enable new innovative solutions to traditional design problems.
-
-
 Typical usages of 130nm Process Nodes
--------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The `130nm process <https://en.wikichip.org/wiki/130_nm_lithography_process>`_ was first commercialized around the 2001-2002 time frame and is now primarily used in the area of research, small microcontroller development, and mixed signal embedded designs such as IoT devices.
 
-A living Google document at <https://j.mp/si130nm> has been created to provide **inspiration** from what researchers, commercial entities and other groups have done with similar **sized** process nodes. As there are widely different constraints and possibilities from changes in both the manufacturing process and materials it is important **not** to assumed that the exact results found in the `130nm inspiration document <https://j.mp/si130>`_ can be identically reproduced on the `SKY130 Process Node`_.
-
-
 PDK Contents
 ============
 

docs/status.rst

@@ -9,7 +9,7 @@ While the SKY130 process node and the PDK from which this open source release wa
 
 Google, SkyWater and our partners are currently doing internal validation and test designs, including silicon validation or the released data and plan to publish these results.
 
-The PDK will be tagged with a production version when ready to do production design, see the `"Versioning Information" <>`_ section for a full description of the version numbering scheme.
+The PDK will be tagged with a production version when ready to do production design, see the ":ref:`Versioning Information`" section for a full description of the version numbering scheme.
 
 To get notified about future new releases of the PDK, and other important news, please sign up on the
 `skywater-pdk-announce mailing list <https://groups.google.com/forum/#!forum/skywater-pdk-announce>`_

docs/versioning.rst

@@ -1,5 +1,5 @@
-Version Numbering
+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.
 

environment.yml

@@ -0,0 +1,7 @@
+name: skywater-pdk-scripts
+dependencies:
+- python
+- pip
+# Packages installed from PyPI
+- pip:
+  - -r file:requirements.txt

requirements.txt

@@ -0,0 +1,3 @@
+# rst_include tool as GitHub doesn't support `.. include::` when rendering
+# previews.
+rst_include

scripts/make/conda.mk

@@ -0,0 +1,88 @@
+# 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
+
+SHELL := /bin/bash
+
+UNAME_S := $(shell uname -s)
+ifneq (, $(findstring Linux, $(UNAME_S)))
+        OSFLAG := Linux
+endif
+ifeq ($(UNAME_S), Darwin)
+        OSFLAG := MacOSX
+endif
+ifneq (, $(findstring Cygwin, $(UNAME_S)))
+        OSFLAG := Linux
+endif
+ifneq (, $(findstring MINGW, $(UNAME_S)))
+        OSFLAG := Linux
+endif
+
+TOP_DIR	          := $(shell git rev-parse --show-toplevel)
+ENV_DIR           := $(TOP_DIR)/env
+REQUIREMENTS_FILE := $(TOP_DIR)/requirements.txt
+ENVIRONMENT_FILE  := $(TOP_DIR)/environment.yml
+
+CONDA_DIR         := $(ENV_DIR)/conda
+DOWNLOADS_DIR     := $(ENV_DIR)/downloads
+CONDA_PYTHON      := $(CONDA_DIR)/bin/python
+CONDA_PKGS_DIR    := $(DOWNLOADS_DIR)/conda-pkgs
+CONDA_PKGS_DEP    := $(CONDA_PKGS_DIR)/urls.txt
+CONDA_ENV_NAME    := skywater-pdk-scripts
+CONDA_ENV_PYTHON  := $(CONDA_DIR)/envs/$(CONDA_ENV_NAME)/bin/python
+IN_CONDA_ENV_BASE := source $(CONDA_DIR)/bin/activate &&
+IN_CONDA_ENV      := $(IN_CONDA_ENV_BASE) conda activate $(CONDA_ENV_NAME) &&
+
+$(ENV_DIR): | $(DOWNLOADS_DIR)
+	mkdir -p $(END_DIR)
+
+$(DOWNLOADS_DIR):
+	mkdir -p $(DOWNLOADS_DIR)
+
+$(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh: | $(DOWNLOADS_DIR)
+	wget https://repo.anaconda.com/miniconda/Miniconda3-latest-$(OSFLAG)-x86_64.sh -O $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+	chmod a+x $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+
+$(CONDA_PKGS_DEP): $(CONDA_PYTHON)
+	$(IN_CONDA_ENV_BASE) conda config --system --add pkgs_dirs $(CONDA_PKGS_DIR)
+
+$(CONDA_PYTHON): $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+	$(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh -p $(CONDA_DIR) -b -f
+
+$(CONDA_DIR)/envs: $(CONDA_PYTHON)
+	$(IN_CONDA_ENV_BASE) conda config --system --add envs_dirs $(CONDA_DIR)/envs
+
+$(CONDA_ENV_PYTHON): $(ENVIRONMENT_FILE) $(REQUIREMENTS_FILE) | $(CONDA_PYTHON) $(CONDA_DIR)/envs $(CONDA_PKGS_DEP)
+	$(IN_CONDA_ENV_BASE) conda env update --name $(CONDA_ENV_NAME) --file $(ENVIRONMENT_FILE)
+
+env: $(CONDA_ENV_PYTHON)
+	$(IN_CONDA_ENV) conda info
+
+.PHONY: env
+
+enter: $(CONDA_ENV_PYTHON)
+	$(IN_CONDA_ENV) bash
+
+.PHONY: enter
+
+clean:
+	rm -rf env/conda
+
+.PHONY: clean
+
+dist-clean:
+	rm -rf conda
+
+.PHONY: dist-clean

scripts/make/git.mk

@@ -0,0 +1,20 @@
+# 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.
+
+FULL_VERSION := $(shell git describe --long)
+TAG_VERSION  := $(firstword $(subst -, ,$(FULL_VERSION)))
+
+ifeq (,$(FULL_VERSION))
+$(error "Version value could not be determined. Make sure you fetch the tags.")
+endif