Use black for formatting

.github/workflows/ci.yml

@@ -12,7 +12,23 @@ on:
 
 jobs:
 
-  build:
+  Format:
+    name: 🐍 Format
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: 🧰 Checkout
+      uses: actions/checkout@v2
+
+    - name: 🐍 Setup Python ${{ matrix.pyver }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.10'
+
+    - name: 🚦 Run pre-commit Action
+      uses: pre-commit/[email protected]
+
+  Build:
     strategy:
       fail-fast: false
       matrix:

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+# Configuration for pre-commit (https://pre-commit.com/), a tool to run
+# formatters, linters, and other productivity tools before a commit.
+repos:
+  - repo: https://github.com/psf/black
+    rev: 21.7b0
+    hooks:
+      - id: black

dev-requirements.txt

@@ -0,0 +1,2 @@
+pre-commit>=2.9.0
+tox

doc/conf.py

@@ -15,51 +15,52 @@
 from datetime import datetime
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('../tests/'))
-sys.path.insert(0, os.path.abspath('../tests/test_vunit/vunit_mock/'))
+
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../tests/"))
+sys.path.insert(0, os.path.abspath("../tests/test_vunit/vunit_mock/"))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'Edalize'
-copyright = '2019-{}, Olof Kindgren'.format(datetime.now().year)
-author = 'Olof Kindgren'
+project = "Edalize"
+copyright = "2019-{}, Olof Kindgren".format(datetime.now().year)
+author = "Olof Kindgren"
 
 # The short X.Y version
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags
-release = '0.1.3'
+release = "0.1.3"
 
 
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = '3.0'
+needs_sphinx = "3.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
-    'sphinx_autodoc_typehints',
-    'sphinx.ext.intersphinx',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.intersphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -71,13 +72,15 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'vunit': ('https://vunit.github.io/', None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "vunit": ("https://vunit.github.io/", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -93,13 +96,16 @@
 
 try:
     import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
+
+    html_theme = "sphinx_rtd_theme"
 except ImportError:
-    sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was '+
-        'not found. Make sure you have the theme installed to produce pretty '+
-        'HTML output. Falling back to the default theme.\n')
+    sys.stderr.write(
+        "Warning: The Sphinx 'sphinx_rtd_theme' HTML theme was "
+        + "not found. Make sure you have the theme installed to produce pretty "
+        + "HTML output. Falling back to the default theme.\n"
+    )
 
-    html_theme = 'alabaster'
+    html_theme = "alabaster"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -126,7 +132,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Edalizedoc'
+htmlhelp_basename = "Edalizedoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -135,15 +141,12 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -153,19 +156,15 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'Edalize.tex', 'Edalize Documentation',
-     'Olof Kindgren', 'manual'),
+    (master_doc, "Edalize.tex", "Edalize Documentation", "Olof Kindgren", "manual"),
 ]
 
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'edalize', 'Edalize Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "edalize", "Edalize Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -174,9 +173,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'Edalize', 'Edalize Documentation',
-     author, 'Edalize', 'Edalize is a Python Library for interacting with EDA tools.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "Edalize",
+        "Edalize Documentation",
+        author,
+        "Edalize",
+        "Edalize is a Python Library for interacting with EDA tools.",
+        "Miscellaneous",
+    ),
 ]
 
 
@@ -195,7 +200,7 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 
 # -- Extension configuration -------------------------------------------------

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 <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

doc/genindex.rst

@@ -0,0 +1,4 @@
+.. # This file is a placeholder and will be replaced
+
+Index
+#####

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 <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>

doc/py-modindex.rst

@@ -0,0 +1,4 @@
+.. # This file is a placeholder and will be replaced
+
+Search Page
+###########

edalize/__init__.py

@@ -7,21 +7,23 @@
 from pkgutil import walk_packages
 
 NON_TOOL_PACKAGES = [
-    'vunit_hooks',
-    'reporting',
-    'ise_reporting',
-    'vivado_reporting',
-    'quartus_reporting',
+    "vunit_hooks",
+    "reporting",
+    "ise_reporting",
+    "vivado_reporting",
+    "quartus_reporting",
 ]
 
+
 def get_edatool(name):
-    return getattr(import_module('{}.{}'.format(__name__, name)),
-                   name.capitalize())
+    return getattr(import_module("{}.{}".format(__name__, name)), name.capitalize())
+
 
 def walk_tool_packages():
     for _, pkg_name, _ in walk_packages([dirname(__file__)]):
         if not pkg_name in NON_TOOL_PACKAGES:
             yield pkg_name
 
+
 def get_edatools():
     return [get_edatool(pkg) for pkg in walk_tool_packages()]