From fd383e58ca65ab095b16e89a11db761a4142c6eb Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Sun, 31 Jul 2022 09:51:46 +0100 Subject: [PATCH 1/3] docs: keep track of relevant changes Signed-off-by: Unai Martinez-Corral --- docs/.gitignore | 1 + docs/changes.py | 87 ++++++++++++++++++++++++++++++++ docs/changes.yml | 98 ++++++++++++++++++++++++++++++++++++ docs/conf.py | 7 +++ docs/development/changes.rst | 4 ++ docs/requirements.txt | 1 + 6 files changed, 198 insertions(+) create mode 100644 docs/changes.py create mode 100644 docs/changes.yml create mode 100644 docs/development/changes.rst 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..81ea025 --- /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: antmicro/f4pga-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: antmicro/f4pga-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/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 From 355117223d935edc28524d4065e1714746949528 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Mon, 1 Aug 2022 12:49:14 +0200 Subject: [PATCH 2/3] docs/index: update Signed-off-by: Unai Martinez-Corral --- docs/index.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) 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 From ec99f9d8b42706aa67bf270ffae2cff816582be7 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Mon, 1 Aug 2022 12:35:46 +0200 Subject: [PATCH 3/3] docs/changes: examples was updated Signed-off-by: Unai Martinez-Corral --- docs/changes.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/changes.yml b/docs/changes.yml index 81ea025..293babf 100644 --- a/docs/changes.yml +++ b/docs/changes.yml @@ -38,7 +38,7 @@ 4: - examples: antmicro/f4pga-examples@52bc71a0506cad647951a16fb214ea82934bed0a + examples: 52bc71a0506cad647951a16fb214ea82934bed0a arch-defs: 20220729-181657@7833050 f4pga: df55ee75e4a1da978ffa5f7385bed47faf255661 <<: *tarballs-consistent @@ -48,7 +48,7 @@ 3: - examples: antmicro/f4pga-examples@d8134c926167a8092d5b392110ce2932bdae8f54 + examples: d8134c926167a8092d5b392110ce2932bdae8f54 arch-defs: 20220729-181657@7833050 f4pga: 8c411eb74e4bb23d1ec243a1515b9bfb48e2cd83 <<: *tarballs-consistent