diff --git a/docs/.gitignore b/docs/.gitignore index 5a49d63..cd58567 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,3 +1,4 @@ /_build/ /env/ /status.inc +/development/changes.inc diff --git a/docs/changes.py b/docs/changes.py new file mode 100644 index 0000000..537607c --- /dev/null +++ b/docs/changes.py @@ -0,0 +1,87 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020-2022 F4PGA 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 +# +# http://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 + +from pathlib import Path +from textwrap import indent + +from yaml import load as yaml_load, Loader as yaml_loader + + +ROOT = Path(__file__).resolve().parent + + +def repo_url(repo, value): + ref = value + if '@' in value: + parts = value.split('@') + repo = parts[0] + ref = parts[1] + return f'https://github.com/{repo}/commit/{ref}' + + +def generate_changes_inc(): + + with open(ROOT / "changes.yml") as data_file: + changes_yml = yaml_load(data_file, yaml_loader) + + with (ROOT / "development/changes.inc").open("w", encoding="utf-8") as wfptr: + revs = sorted(changes_yml.keys()) + + wfptr.write(''' +Tested environments +===================\n +''') + + for item in reversed(revs[1:]): + + f4pga = changes_yml[revs[item]]['f4pga'] + examples = changes_yml[revs[item]]['examples'] + + arch_defs = changes_yml[revs[item]]['arch-defs'].split('@') + arch_defs_timestamp = arch_defs[0] + arch_defs_hash = arch_defs[1] + + tarballs = changes_yml[revs[item]]['tarballs'] + eos_s3 = ' '.join([f"* ``{item}``\n" for item in tarballs['eos-s3']]) + xc7 = ' '.join([f"* ``{item}``\n" for item in tarballs['xc7']]) + + wfptr.write(f''' +{revs[item]} +--- + +.. NOTE:: +{indent(changes_yml[revs[item]]['description'], ' ')} + +* Examples: `{examples} <{repo_url("chipsalliance/f4pga-examples", examples)}>`__ +* CLI: `{f4pga} <{repo_url("chipsalliance/f4pga",f4pga)}>`__ +* Architecture Definitions: {arch_defs[0]} @ `{arch_defs[1]} `__ + + * xc7 + + {xc7} + * eos-s3 + + {eos_s3} +''') + + wfptr.write(''' +Future work +===========\n +''') + wfptr.write(changes_yml[revs[0]]['future-work']) diff --git a/docs/changes.yml b/docs/changes.yml new file mode 100644 index 0000000..293babf --- /dev/null +++ b/docs/changes.yml @@ -0,0 +1,98 @@ +# Copyright (C) 2020-2022 F4PGA 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 +# +# http://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 + +0: + future-work: | + - Python scripts moved from f4pga-arch-defs to f4pga. + - TCL scripts moved from f4pa-arch-defs to f4pga. + - `f4pga build` now supports Lattice's ICE40 devices. + - `f4pga build` now supports Lattice's ECP5 devices. + - `f4pga build` now supports Lattice's NX devices. + 5: + examples: '' + arch-defs: 20220729-181657@7833050 + f4pga: '' + <<: &tarballs-consistent + tarballs: + xc7: + - symbiflow-install-xc7-*-tar-xz + - symbiflow-arch-defs-xc7a50t_test-*.tar.xz + eos-s3: + - symbiflow-install-ql-*-tar-xz + - symbiflow-ql-eos-s3_wlcsp-*-tar-xz + description: | + ``f4pga build`` now supports QuickLogic's EOS-S3 devices. + + +4: + examples: 52bc71a0506cad647951a16fb214ea82934bed0a + arch-defs: 20220729-181657@7833050 + f4pga: df55ee75e4a1da978ffa5f7385bed47faf255661 + <<: *tarballs-consistent + description: | + The default F4PGA_SHARE_DIR is now consistent for AMD/Xilinx or QuickLogic: + ``F4PGA_INSTALL_DIR / FPGA_FAM / 'install/share/f4pga'``. + + +3: + examples: d8134c926167a8092d5b392110ce2932bdae8f54 + arch-defs: 20220729-181657@7833050 + f4pga: 8c411eb74e4bb23d1ec243a1515b9bfb48e2cd83 + <<: *tarballs-consistent + description: | + Architecture Definitions: + + * AMD/Xilinx base package is now ``*-install-xc7-*``. + + * QuickLogic now has a base package named ``*-install-ql-*``. + + * Python scripts in QuickLogic packages moved from ``bin/python`` to ``share/f4pga/scripts``. + + * Share paths modified: + + * AND/Xilinx and QuickLogic arch-defs packages homogenized. + + * ``s/symbiflow/f4pga/`` + + +2: + examples: 3e8a003cabec84f7841571a6929fe2623e702e96 + arch-defs: 20220721-204939@38358c4 + f4pga: 27eca4f35db3c4e04ce255ab319611774de9b9a1 + <<: &tarballs-split + tarballs: + xc7: + - symbiflow-arch-defs-install-*.tar.xz + - symbiflow-arch-defs-xc7a50t_test-*.tar.xz + eos-s3: + - quicklogic-arch-defs-qlf-fc5d8da.tar.gz + description: | + * Environment variables were renamed and are now supported by ``f4pga build``: + + * ``s/F4PGA_ENV_BIN/F4PGA_BIN_DIR/`` + + * ``s/F4PGA_ENV_SHARE/F4PGA_SHARE_DIR/`` + + * f4pga is now pinned in the requirements files of f4pga-examples. + + +1: + examples: 6b0e7b8a75fb8715bb081cb7f24948c3aec0df31 + arch-defs: 20220714-173445@f7afc12 + f4pga: 39da9c9f17513ea0c3dd12be655a3684e5b77519 + <<: *tarballs-split + description: | + First release being tracked. diff --git a/docs/conf.py b/docs/conf.py index 538f5f3..21883cc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,13 @@ from tabulate import tabulate ROOT = Path(__file__).resolve().parent #sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, str(ROOT)) + +from changes import generate_changes_inc + +# -- Generate development/changes.inc ---------------------------------------------------------------------------------- + +generate_changes_inc() # -- Generate status.inc ----------------------------------------------------------------------------------------------- diff --git a/docs/development/changes.rst b/docs/development/changes.rst new file mode 100644 index 0000000..4c88cb5 --- /dev/null +++ b/docs/development/changes.rst @@ -0,0 +1,4 @@ +Changes +####### + +.. include:: changes.inc diff --git a/docs/index.rst b/docs/index.rst index f952b51..683973d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,6 @@ The project aims to design tools that are highly extendable and multiplatform. :align: center - .. toctree:: :caption: About F4PGA @@ -20,6 +19,24 @@ The project aims to design tools that are highly extendable and multiplatform. getting-started +.. toctree:: + :caption: Python utils + :maxdepth: 2 + + f4pga/index + f4pga/Usage + f4pga/modules/index + f4pga/DevNotes + + +.. toctree:: + :caption: Development + + development/changes + development/building-docs + development/venv + + .. toctree:: :caption: Design Flows @@ -36,23 +53,6 @@ The project aims to design tools that are highly extendable and multiplatform. FPGA Assembly (FASM) ➚ -.. toctree:: - :caption: Development - - contributing/building-docs - contributing/venv - - -.. toctree:: - :caption: Python utils - :maxdepth: 2 - - f4pga/index - f4pga/Usage - f4pga/modules/index - f4pga/DevNotes - - .. toctree:: :caption: Appendix diff --git a/docs/requirements.txt b/docs/requirements.txt index e87e470..44c25a3 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ myst-parser +pyyaml sphinx>=4.5.0 sphinxcontrib-bibtex https://github.com/f4pga/sphinx_f4pga_theme/archive/f4pga.zip#sphinx-f4pga-theme