From bf6e4cbf6c0799d70bd86ce49c3c663f57ac3d54 Mon Sep 17 00:00:00 2001 From: umarcor Date: Wed, 3 Nov 2021 14:05:14 +0100 Subject: [PATCH] [Doc] Restructure to be easier to navigate, and document usage of pre-commit * Add section "Edalize Developer's Guide" * Reduce hierarchy complexity * [Tests/Readme] reduce hierarchy * Remove ref to empty Search Page * Make 'Indices and tables' a toctree * Make "Developer's Guide" a toctree --- doc/dev/setup.rst | 50 +++++++++++++++++++++++++++++++++++ doc/{source => dev}/tests.rst | 0 doc/{source => }/edalize.rst | 0 doc/genindex.rst | 4 +++ doc/index.rst | 25 +++++++++++------- doc/py-modindex.rst | 4 +++ doc/source/modules.rst | 7 ----- tests/README.rst | 13 +++------ 8 files changed, 78 insertions(+), 25 deletions(-) create mode 100644 doc/dev/setup.rst rename doc/{source => dev}/tests.rst (100%) rename doc/{source => }/edalize.rst (100%) create mode 100644 doc/genindex.rst create mode 100644 doc/py-modindex.rst delete mode 100644 doc/source/modules.rst diff --git a/doc/dev/setup.rst b/doc/dev/setup.rst new file mode 100644 index 000000000..4083a3da8 --- /dev/null +++ b/doc/dev/setup.rst @@ -0,0 +1,50 @@ +Development Setup +================= + +Setup development environment +----------------------------- + +.. note:: + + If you have already installed Edalize, remove it first using ``pip3 uninstall edalize``. + +To develop Edalize and test the changes, the edalize package needs to be installed in editable or development mode. +In this mode, the ``edalize`` command is linked to the source directory, and changes made to the source code are +immediately visible when calling ``edalize``. + +.. code-block:: bash + + # Install all Python packages required to develop edalize + pip3 install --user -r dev-requirements.txt + + # Install Git pre-commit hooks, e.g. for the code formatter and lint tools + pre-commit install + + # Install the edalize package in editable mode + pip3 install --user -e . + +.. note:: + + All commands above use Python 3 and install software only for the current user. + If, after this installation, the ``edalize`` command cannot be found adjust your ``PATH`` environment variable to + include ``~/.local/bin``. + +After this installation is completed, you can + +* edit files in the source directory and re-run ``edalize`` to immediately see the changes, +* run the unit tests as outlined in the section below, and +* use linter and automated code formatters. + +Formatting and linting code +--------------------------- + +The Edalize code comes with tooling to automatically format code to conform to our expectations. +These tools are installed and called through a tool called `pre-commit `_. +No setup is required: whenever you do a ``git commit``, the necessary tools are called and your code is automatically formatted and checked for common mistakes. + +To check the whole source code ``pre-commit`` can be run directly: + +.. code-block:: bash + + # check and fix all files + pre-commit run -a diff --git a/doc/source/tests.rst b/doc/dev/tests.rst similarity index 100% rename from doc/source/tests.rst rename to doc/dev/tests.rst diff --git a/doc/source/edalize.rst b/doc/edalize.rst similarity index 100% rename from doc/source/edalize.rst rename to doc/edalize.rst diff --git a/doc/genindex.rst b/doc/genindex.rst new file mode 100644 index 000000000..d4fc2f48f --- /dev/null +++ b/doc/genindex.rst @@ -0,0 +1,4 @@ +.. # This file is a placeholder and will be replaced + +Index +##### diff --git a/doc/index.rst b/doc/index.rst index fa501d522..4ca892032 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,19 +18,26 @@ Welcome to Edalize's documentation! =================================== +Edalize is a Python Library for interacting with EDA tools. +It can create project files for supported tools and run them in batch or GUI mode (where supported). + .. toctree:: - :maxdepth: 2 - :caption: Contents: + :caption: Reference + :hidden: edam/api - source/modules - source/tests + Modules +.. toctree:: + :caption: Developer's Guide + :hidden: -Indices and tables -================== + dev/setup + dev/tests +.. toctree:: + :caption: Indices and tables + :hidden: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + genindex + Module Index diff --git a/doc/py-modindex.rst b/doc/py-modindex.rst new file mode 100644 index 000000000..5f07d3e25 --- /dev/null +++ b/doc/py-modindex.rst @@ -0,0 +1,4 @@ +.. # This file is a placeholder and will be replaced + +Search Page +########### diff --git a/doc/source/modules.rst b/doc/source/modules.rst deleted file mode 100644 index 9908a3228..000000000 --- a/doc/source/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -Modules -======= - -.. toctree:: - :maxdepth: 4 - - edalize diff --git a/tests/README.rst b/tests/README.rst index d9e452949..c166e6391 100644 --- a/tests/README.rst +++ b/tests/README.rst @@ -1,17 +1,11 @@ -*************** Testing edalize -*************** - -Users -===== +############### To run the tests, call :command:`pytest`. -Developers -========== Mocks for commands ------------------- +================== We provide mocks (stand-ins) for all tools that we want to exercise in tests (located in :file:`tests/mock_commands/`). These mocks are very simplified "models" of the actual tool, and are called instead of the actual tool. @@ -25,8 +19,9 @@ In a more complex test setup (e.g. for ``vcs``), * we make the file executable * we set the access and modified times of generated files to the current time + Testcases ---------- +========= To define a testcase, use the :func:`edalize_common.make_edalize_test` pytest factory fixture. This defines a factory that you can call to set up a mocked-up backend appropriately.