Skip to content

Commit

Permalink
[Doc] Restructure to be easier to navigate, and document usage of
Browse files Browse the repository at this point in the history
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
  • Loading branch information
umarcor authored and olofk committed Nov 5, 2021
1 parent aca7920 commit 64963c6
Show file tree
Hide file tree
Showing 8 changed files with 78 additions and 25 deletions.
50 changes: 50 additions & 0 deletions doc/dev/setup.rst
Original file line number Diff line number Diff line change
@@ -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 <https://pre-commit.com/>`_.
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
File renamed without changes.
File renamed without changes.
4 changes: 4 additions & 0 deletions doc/genindex.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. # This file is a placeholder and will be replaced
Index
#####
25 changes: 16 additions & 9 deletions doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <edalize>

.. 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 <py-modindex>
4 changes: 4 additions & 0 deletions doc/py-modindex.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. # This file is a placeholder and will be replaced
Search Page
###########
7 changes: 0 additions & 7 deletions doc/source/modules.rst

This file was deleted.

13 changes: 4 additions & 9 deletions tests/README.rst
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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.
Expand Down

0 comments on commit 64963c6

Please sign in to comment.