Commit f2fda16b authored by Sean Leavey's avatar Sean Leavey
Browse files

Fix docs and pyproject.toml trailing comma

parent fe91c9a0
......@@ -14,50 +14,47 @@ allowing users to use different frontends (such as `pip
<https://pip.pypa.io/en/stable/>`__ or `poetry <https://python-poetry.org/>`__) without
requiring changes to the |Finesse| configuration.
:pep:`517` specifies that *build* dependencies are defined in :source:`pyproject.toml
</pyproject.toml>` and *runtime* and *extra* dependencies are defined in
:source:`setup.cfg </setup.cfg>` and/or :source:`setup.py </setup.py>`. This way, build
dependencies are kept separate and are known without having to execute any Python code,
which makes it possible to build projects in isolation and prevents a few error classes
(see :pep:`the PEP description <517>` for more information). It's not strictly necessary
to use *both* :source:`setup.cfg </setup.cfg>` and/or :source:`setup.py </setup.py>` for
specifying runtime and extra dependencies; it's recommended to use the declarative
:source:`setup.cfg </setup.cfg>` if possible. In |Finesse|, however, the need to build
Cython extensions requires some special logic that is not easily implemented in
:source:`setup.cfg </setup.cfg>` and is therefore instead defined in :source:`setup.py
</setup.py>`.
PEP 517 specifies that *build* dependencies are defined in ``pyproject.toml`` and
*runtime* and *extra* dependencies are defined in ``setup.cfg`` and/or ``setup.py``.
This way, build dependencies are kept separate and are known without having to execute
any Python code, which makes it possible to build projects in isolation and prevents a
few error classes (see the PEP 517 description for more information). It's not strictly
necessary to use *both* ``setup.cfg`` and/or ``setup.py`` for specifying runtime and
extra dependencies; it's recommended to use the declarative ``setup.cfg`` if possible.
In |Finesse|, however, the need to build Cython extensions requires some special logic
that is not easily implemented in ``setup.cfg`` and is therefore instead defined in
``setup.py``.
Settings for various development tools can also often be stored in their own sections in
:source:`setup.cfg </setup.cfg>` or :source:`pyproject.toml </pyproject.toml>`. For
|Finesse| it is preferable to use :source:`pyproject.toml </pyproject.toml>` for such
settings, but not all tools support it (e.g. ``flake8``) so some settings are stored
also in the former.
``setup.cfg`` or ``pyproject.toml``. For |Finesse| it is preferable to use
``pyproject.toml`` for such settings, but not all tools support it (e.g. ``flake8``) so
some settings are stored also in the former.
In addition to Python dependencies, |Finesse| requires some system dependencies in order
to be built. These are not required for end users using an appropriate wheel. These are
independent of Python and are therefore not specified in :source:`setup.cfg
</setup.cfg>`.
independent of Python and are therefore not specified in ``setup.cfg``.
.. note::
:pep:`517` recommends (but does not strictly require) that build tools build projects
in isolation. This means that build dependencies (see below) are installed in a
PEP 517 recommends (but does not strictly require) that build tools build projects in
isolation. This means that build dependencies (see below) are installed in a
temporary location, used only for the building of the package, then deleted when the
built package is installed in the user's environment. This is usually beneficial
because it means build dependencies (such as Cython) don't need to be available in
the local environment, but when debugging build issues it may be useful to switch
this behaviour off. In ``pip`` this can be done with the ``--no-build-isolation``
flag when running ``pip install``.
flag when running ``pip install``. Note that you'll need to ensure the build
dependencies listed in ``pyproject.toml`` are available.
Modifying dependencies
----------------------
Runtime dependencies, i.e. those required for running |Finesse| on a user's computer,
are listed in the ``install_requires`` key of the ``[options]`` section of
:source:`setup.cfg </setup.cfg>`. As |Finesse| is widely used on many different
platforms, runtime dependencies should in general be minimised to mitigate the risk of
`resolution issues <https://en.wikipedia.org/wiki/Dependency_hell>`__, and, where
unavoidable, should ideally favour popular, widely used packages.
``setup.cfg``. As |Finesse| is widely used on many different platforms, runtime
dependencies should in general be minimised to mitigate the risk of `resolution issues
<https://en.wikipedia.org/wiki/Dependency_hell>`__, and, where unavoidable, should
ideally favour popular, widely used packages.
It's important for runtime dependencies to be **pinned**, i.e. set to specific or
narrowly defined ranges of versions. This reduces the risk that updates to dependencies
......@@ -69,11 +66,11 @@ Other project dependencies are required only for building |Finesse| into package
distribution to users and to assist with the development:
- *Build* dependencies are defined in the ``requires`` key within the ``[build-system]``
section of :source:`pyproject.toml </pyproject.toml>`.
section of ``pyproject.toml``.
- *Extra* dependencies are defined in the ``[options.extras_require]`` section of
:source:`setup.cfg </setup.cfg>`. Listed here are keys and values representing groups
of extra dependencies of a certain topic. For example, the key ``docs`` lists
dependencies required for building the documentation.
``setup.cfg``. Listed here are keys and values representing groups of extra
dependencies of a certain topic. For example, the key ``docs`` lists dependencies
required for building the documentation.
Adding a new required package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -93,7 +90,7 @@ requirements categories.
3. Ascertain the category that the requirement falls under and the location that the
requirement must therefore be listed - i.e. if it is a package needed for a new
documentation feature then it should be added to the ``[options.extras_require]``
section of :source:`setup.cfg </setup.cfg>`.
section of ``setup.cfg``.
4. Add the package name (*and pinned version(s)*, if it's a runtime dependency) to the
relevant requirements file. The format is defined by :pep:`508`. For example, if the
......
......@@ -150,8 +150,9 @@ various situations:
- `:kat:element:\`element_name\`` to create a link to a kat-script element,
- `:kat:analysis:\`analysis_name\`` to create a link to a kat-script analysis,
- `:issue:`123`` to create a link to an issue on the tracker,
- `:source:`script/compiler.py`` to create a link to a source code file (relative to
``/src/finesse/``).
- `:source:`path/to/script.py`` to create a link to a source code file relative to
the |Finesse| package root (i.e. ``/src/finesse/``), or `:source:`/path/to/script.py``
to create a link to a source code file relative to the project root.
An example of cross-referencing is shown below for the :meth:`.Model.path` method::
......
......@@ -7,9 +7,9 @@ Running and writing tests
**Source code:** :source:`tests </tests>`
|Finesse| contains a :source:`large suite of tests </tests>`. These are run
automatically when changes are made to the code and pushed to the git repository, but
can also be run manually with `pytest`.
|Finesse| contains a large suite of tests. These are run automatically when changes are
made to the code and pushed to the git repository, but can also be run manually with
`pytest`.
.. note::
......@@ -42,8 +42,8 @@ tests, simply run Pytest (you must have installed |Finesse| in :ref:`developer m
.. note::
Pytest is configured in :source:`setup.cfg </setup.cfg>` to run tests in the
:source:`tests </tests>` directory by default.
Pytest is configured in :source:`pyproject.toml </pyproject.toml>` to run tests in
the :source:`tests </tests>` directory by default.
Pytest's CLI can run individual or combinations of tests by specifying specific
subdirectories, modules or even particular functions. For instance, `functional tests
......
......@@ -38,7 +38,7 @@ Via Conda
From source
-----------
.. see-also::
.. seealso::
If you want to contribute to the *development* of |Finesse| then you should rather
read :ref:`dev_get_started`.
......
......@@ -4,7 +4,7 @@ requires = [
"wheel",
"setuptools_scm[toml]",
"Cython",
"numpy == 1.20.3", # Should match that in setup.cfg install_requires.
"numpy == 1.20.3" # Should match that in setup.cfg install_requires.
]
build-backend = "setuptools.build_meta"
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment