From 60e7c8505e0c3973dd874f04a829f1c03af56cf7 Mon Sep 17 00:00:00 2001 From: Unai Martinez-Corral Date: Sun, 27 Feb 2022 14:26:29 +0100 Subject: [PATCH] mv f4pga/docs docs/f4pga Signed-off-by: Unai Martinez-Corral --- docs/conf.py | 6 +++++- .../f4pga/CommonTargetsAndVariables.md | 8 ++++---- {f4pga/docs => docs/f4pga}/DevNotes.md | 0 {f4pga/docs => docs/f4pga}/GettingStarted.md | 0 {f4pga/docs => docs/f4pga}/Module.md | 0 {f4pga/docs => docs/f4pga}/browse_pydoc.sh | 4 ++-- .../f4pga}/common/generic_script_wrapper.md | 14 ++++---------- docs/f4pga/common/index.rst | 9 +++++++++ .../modules => docs/f4pga}/common/io_rename.md | 14 ++++---------- .../docs/modules => docs/f4pga}/common/mkdirs.md | 8 ++------ .../docs/modules => docs/f4pga}/common/synth.md | 12 +++--------- docs/index.rst | 16 ++++++++++++++-- docs/requirements.txt | 1 + 13 files changed, 48 insertions(+), 44 deletions(-) rename f4pga/docs/common targets and variables.md => docs/f4pga/CommonTargetsAndVariables.md (90%) rename {f4pga/docs => docs/f4pga}/DevNotes.md (100%) rename {f4pga/docs => docs/f4pga}/GettingStarted.md (100%) rename {f4pga/docs => docs/f4pga}/Module.md (100%) rename {f4pga/docs => docs/f4pga}/browse_pydoc.sh (50%) rename {f4pga/docs/modules => docs/f4pga}/common/generic_script_wrapper.md (93%) create mode 100644 docs/f4pga/common/index.rst rename {f4pga/docs/modules => docs/f4pga}/common/io_rename.md (86%) rename {f4pga/docs/modules => docs/f4pga}/common/mkdirs.md (65%) rename {f4pga/docs/modules => docs/f4pga}/common/synth.md (92%) diff --git a/docs/conf.py b/docs/conf.py index 281dd71..1fb9030 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,6 +47,7 @@ extensions = [ 'sphinx.ext.intersphinx', 'sphinx_verilog_domain', 'sphinxcontrib.bibtex', + 'recommonmark' ] bibtex_default_style = 'plain' @@ -56,7 +57,10 @@ numfig = True templates_path = ['_templates'] -source_suffix = ['.rst', '.md'] +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown' +} master_doc = 'index' diff --git a/f4pga/docs/common targets and variables.md b/docs/f4pga/CommonTargetsAndVariables.md similarity index 90% rename from f4pga/docs/common targets and variables.md rename to docs/f4pga/CommonTargetsAndVariables.md index 52d68af..3e24b60 100644 --- a/f4pga/docs/common targets and variables.md +++ b/docs/f4pga/CommonTargetsAndVariables.md @@ -3,7 +3,7 @@ Targets and values are named with some conventions. Below are lists of the target and value names along with their meanings" -### Common targets that need to be provided by the user: +## Common targets that need to be provided by the user: | Target name | list | Description | |-------------|:----:|-------------| @@ -12,7 +12,7 @@ Below are lists of the target and value names along with their meanings" | `xdc` | yes | Xilinx Design Constraints (available only for Xilinx platforms) | | `pcf` | no | Physical Constraints File | -### Commonly requested targets (available in most flows): +## Commonly requested targets (available in most flows): | Target name | list | Description | |-------------|:----:|-------------| @@ -23,7 +23,7 @@ Below are lists of the target and value names along with their meanings" | `fasm_extra` | no | Additional FPGA assembly that may be generated during synthesis | | `build_dir` | no | A directory to put the output files in | -### Built-in values +## Built-in values | Value name | type | Description | |------------|------|-------------| @@ -32,7 +32,7 @@ Below are lists of the target and value names along with their meanings" | `noisyWarnings` | `string` | Path to noisy warnings log (should be deprecated) | | `prjxray_db` | `string` | Path to Project X-Ray database | -### Values commonly used in flow definitions: +## Values commonly used in flow definitions: | Value name | type | Description | |------------|------|-------------| diff --git a/f4pga/docs/DevNotes.md b/docs/f4pga/DevNotes.md similarity index 100% rename from f4pga/docs/DevNotes.md rename to docs/f4pga/DevNotes.md diff --git a/f4pga/docs/GettingStarted.md b/docs/f4pga/GettingStarted.md similarity index 100% rename from f4pga/docs/GettingStarted.md rename to docs/f4pga/GettingStarted.md diff --git a/f4pga/docs/Module.md b/docs/f4pga/Module.md similarity index 100% rename from f4pga/docs/Module.md rename to docs/f4pga/Module.md diff --git a/f4pga/docs/browse_pydoc.sh b/docs/f4pga/browse_pydoc.sh similarity index 50% rename from f4pga/docs/browse_pydoc.sh rename to docs/f4pga/browse_pydoc.sh index d3cae9f..d82dd66 100755 --- a/f4pga/docs/browse_pydoc.sh +++ b/docs/f4pga/browse_pydoc.sh @@ -1,7 +1,7 @@ #!/bin/sh MY_DIR=`dirname $0` -SFBUILD_DIR=${MY_DIR}/.. +SFBUILD_DIR=${MY_DIR}/../../f4pga SFBUILD_PY=${SFBUILD_DIR}/sfbuild.py -PYTHONPATH=${SFBUILD_DIR} pydoc -b \ No newline at end of file +PYTHONPATH=${SFBUILD_DIR} pydoc -b diff --git a/f4pga/docs/modules/common/generic_script_wrapper.md b/docs/f4pga/common/generic_script_wrapper.md similarity index 93% rename from f4pga/docs/modules/common/generic_script_wrapper.md rename to docs/f4pga/common/generic_script_wrapper.md index c6fa7c0..32c2a50 100644 --- a/f4pga/docs/modules/common/generic_script_wrapper.md +++ b/docs/f4pga/common/generic_script_wrapper.md @@ -1,15 +1,9 @@ -# sfbuild module "generic_script_wrapper" - -##### _Category: Common_ - -------------------------------- +# generic_script_wrapper This module provides a way to integrate an external command into an sfbuild flow. Its inputs and outputs are fully defined by the author of flow definition. -## Setup - -### 1. Parameters +## Parameters Parameters are everything when it comes to this module: @@ -29,7 +23,7 @@ Parameters are everything when it comes to this module: dependency alsogets two extra values associated with it: `:dependency_name[noext]`, which contains the path to the dependency the extension with anything after last "." removed and `:dependency_name[dir]` which - contains directory paths of the dependency. This is useful for deriving an output + contains directory paths of the dependency. This is useful for deriving an output name from the input. * `meta` (string, optional): Description of the output dependency. * `inputs` (dict[string -> string | bool], mandatory): @@ -44,4 +38,4 @@ Parameters are everything when it comes to this module: are implicit. If the value of the resolved string is empty and is associated with a named argument, the argument in question will be skipped entirely. This allows using optional dependencies. To use a named argument as a flag instead, set it to - `true`. \ No newline at end of file + `true`. diff --git a/docs/f4pga/common/index.rst b/docs/f4pga/common/index.rst new file mode 100644 index 0000000..348dcc8 --- /dev/null +++ b/docs/f4pga/common/index.rst @@ -0,0 +1,9 @@ +Modules +####### + +.. toctree:: + + generic_script_wrapper + io_rename + mkdirs + synth diff --git a/f4pga/docs/modules/common/io_rename.md b/docs/f4pga/common/io_rename.md similarity index 86% rename from f4pga/docs/modules/common/io_rename.md rename to docs/f4pga/common/io_rename.md index 7c29ff5..4e994d5 100644 --- a/f4pga/docs/modules/common/io_rename.md +++ b/docs/f4pga/common/io_rename.md @@ -1,15 +1,9 @@ -# sfbuild module "io_rename" - -##### _Category: Common_ - -------------------------------- +# io_rename This module provides a way to rename (ie. change) dependencies and values of an instance of a different module. It wraps another, module whoose name is specified in `params.module` and changes the names of the dependencies and values it relies on. -## Setup - -### 1. Parameters +## Parameters * `module` (string, required) - name of the wrapped module * `params` (dict[string -> any], optional): parameters passed to the wrapped @@ -22,6 +16,6 @@ In the three mapping dicts, keys represent the names visible to the wrapped modu and values represent the names visible to the modules outside. Not specifying a mapping for a given entry will leave it with its original name. -### 2. Values +## Values -All values specified for this modules will be accessible by tyhe wrapped module. \ No newline at end of file +All values specified for this modules will be accessible by tyhe wrapped module. diff --git a/f4pga/docs/modules/common/mkdirs.md b/docs/f4pga/common/mkdirs.md similarity index 65% rename from f4pga/docs/modules/common/mkdirs.md rename to docs/f4pga/common/mkdirs.md index 160bdc7..5e778b8 100644 --- a/f4pga/docs/modules/common/mkdirs.md +++ b/docs/f4pga/common/mkdirs.md @@ -1,13 +1,9 @@ -# sfbuild module "io_rename" - -##### _Category: Common_ - -------------------------------- +# io_rename This modules creates directiories specified by the author of flow definition as its targets.. -### Parameters +## Parameters Each key serves as aname of a directory to becreated, while the value is the path for that directory. \ No newline at end of file diff --git a/f4pga/docs/modules/common/synth.md b/docs/f4pga/common/synth.md similarity index 92% rename from f4pga/docs/modules/common/synth.md rename to docs/f4pga/common/synth.md index 394f26e..5478816 100644 --- a/f4pga/docs/modules/common/synth.md +++ b/docs/f4pga/common/synth.md @@ -1,8 +1,4 @@ -# sfbuild module "synth" - -##### _Category: Common_ - -------------------------------- +# synth The _synth_ module is meant to be used to execute YOSYS synthesis. @@ -16,8 +12,6 @@ The module should guarantee the following outputs: For detailed information about these targets, please refer to `docs/common targets and variables.md` -## Setup - What files and how are they generated is dependendent on TCL scripts executed withing YOSYS and the script vary depending on the target platform. Due to this design choice it is required for the author of the flow defnition to parametrize @@ -26,13 +20,13 @@ will be generated upon a successful YOSYS run. The setup of the synth module follows the following specifications: -### 1. Module parameters: +## Parameters: The `params` section of a stage configuration may contain a `produces` list. The list should specify additional targets that will be generated (`?` qualifier is allowedd). -### 2. Values: +## Values: The `synth` module requires the following values: diff --git a/docs/index.rst b/docs/index.rst index bcedf97..21b7f03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ The project aims to design tools that are highly extendable and multiplatform. :align: center + .. toctree:: :caption: About F4PGA @@ -38,8 +39,19 @@ The project aims to design tools that are highly extendable and multiplatform. .. toctree:: :caption: Development - development/building-docs - development/venv + contributing/building-docs + contributing/venv + + +.. toctree:: + :caption: pyF4PGA Reference + :maxdepth: 2 + + f4pga/GettingStarted + f4pga/CommonTargetsAndVariables + f4pga/Module + f4pga/common/index + f4pga/DevNotes .. toctree:: diff --git a/docs/requirements.txt b/docs/requirements.txt index a7505cb..aa87fdf 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +recommonmark sphinx>=4.5.0 sphinxcontrib-bibtex https://github.com/SymbiFlow/sphinx_symbiflow_theme/archive/chips.zip#sphinx-symbiflow-theme