[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

@@ -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
+###########

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.