Commit 1915b653 authored by Sean Leavey's avatar Sean Leavey
Browse files

Update docs

parent 42dbe214
# Finesse3 Documentation Files
# Finesse 3 documentation
These directories contain the reStuctured Text (reST) files (`.rst` extension) making
up the documentation for the `finesse` package. The package `sphinx` is used for
building the documentation with all docstrings in the `finesse` code itself formatted
using the `numpydoc` style (see below).
## Building the documentation
The documentation can be built in several formats by running `make <format>`
where `<format>` can be, for example, `html` or `latex`. The built documentation
files will then be found in `build/` under the directory corresponding to the
format chosen.
### Requirements for the build process
The following components are required to build the documenation for the `finesse` package from this
directory:
- an up-to-date version of [Sphinx](http://www.sphinx-doc.org/en/master/),
- the [Sphinx Read the Docs theme](http://sphinx-rtd-theme.readthedocs.io/en/latest/),
- the [numpydoc extension](https://numpydoc.readthedocs.io/en/latest/install.html),
- the [sphinxcontrib-bibtex extension](http://sphinxcontrib-bibtex.readthedocs.io/en/latest/index.html),
- the [sphinxcontrib-katex extension](https://sphinxcontrib-katex.readthedocs.io/en/latest/index.html),
- and all the requirements for building the `cython` extensions in the `finesse` package (see
the README in the package root directory for information).
### Finding missing class method documentation
This directory contains a script `check_missing.py` which, when run, will show you which functions,
classes and class methods are currently missing from the `source/api` documentation files and so need
to be added. It will also notify of any public functions, classes andclass methods in the source code
which are missing docstrings.
## Writing `numpydoc` docstrings
To produce well formatted API documentation for Finesse, all module, class and function
docstrings will be written in the [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html). If
you installed Python through Anaconda then you should already have the `numpydoc` extension installed, otherwise
run `pip install numpydoc` (or any other suitable package manager such as `conda` or `pacman`) to retrieve
it (note that building the documentation will fail without `numpydoc` installed).
These directories contain the reStuctured Text (reST) files (`.rst` extension) making up
the documentation for the `finesse` package. For information on how to build the
documentation, see the [existing
documentation](https://finesse.docs.ligo.org/finesse3/developer/documenting.html#building-the-documentation).
......@@ -2,34 +2,81 @@
.. _requirements_guide:
Adding and modifying dependencies
*********************************
|Finesse| manages its dependencies via `pip <https://pip.pypa.io/en/stable/>`_ using
``requirements`` files. These files work in conjunction with the Conda ``environment``
file to allow ease-of-use through Conda environments, with a single set of requirements
held in the requirements files to allow other package management tools to be used if you
so wish.
There are four requirements files in total:
- `requirements.txt
<https://git.ligo.org/finesse/finesse3/-/blob/master/requirements.txt>`_ --- core
packages needed to run |Finesse|.
- `requirements-doc.txt
<https://git.ligo.org/finesse/finesse3/-/blob/master/requirements-doc.txt>`_ ---
packages required to build the documentation.
- `requirements-test.txt
<https://git.ligo.org/finesse/finesse3/-/blob/master/requirements-test.txt>`_ ---
packages required to run the |Finesse| test suite.
In addition to the above requirements files, |Finesse| uses separate
``install_requires`` and ``extras_require`` keyword arguments in ``setup.py``. This is
based on following the best practices recommended in the `Python packaging guides
<https://packaging.python.org/discussions/install-requires-vs-requirements/>`_.
Adding a package to the requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Requirements for building, running and developing Finesse
=========================================================
**Source code:** :source:`setup.py </setup.py>`, :source:`setup.cfg </setup.cfg>`,
:source:`pyproject.toml </pyproject.toml>`
|Finesse|'s Python dependencies are specified following the approach defined by
:pep:`517`. This allows for dependencies to be listed in a build system independent way,
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>`.
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.
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>`.
.. 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
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``.
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.
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
break released versions of |Finesse|; this way, if the release is sufficiently well
tested at release time, it should stay "working" for as long as its pinned dependencies
are still available.
Other project dependencies are required only for building |Finesse| into packages for
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>`.
- *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.
Adding a new required package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The process outlined below should be adhered to when adding a package to any of the
requirements categories.
......@@ -43,79 +90,43 @@ requirements categories.
you are adding / changing. You should verify that tests pass with the additional
package on your local machine - see :ref:`testing`.
3. Ascertain the category that the requirement falls under - i.e. if it is a package
needed for a new documentation feature then it should be added to the
``requirements-doc.txt`` file.
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>`.
4. Add the package name *and pinned version* to the relevant requirements file. For
example, if the package is called ``foo`` and the version you want people to use is
``v1.1.0`` then add the line::
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
package is called ``foo`` and the version you want people to use is ``v1.1.0`` then
add the line::
foo == 1.1.0
to the associated requirements file.
to the associated file.
5. Add the package name *without the pinned version* to
Changing the version of a requirement
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a. the ``REQUIRES`` list in ``setup.py`` if it is a core package required to run
|Finesse| OR
b. the ``EXTRAS`` dict in ``setup.py`` if it is any other type of package.
It's generally good to make use of the latest versions of dependencies to benefit from
new features and bug fixes, as long as they are compatible with |Finesse|. This of
course only applies to pinned dependencies.
Changing the pinned version of a requirement
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Follow the steps in the section above for adding new dependencies, but instead find
and modify the version of the existing dependency in the respective file.
Follow the process below to modify the version of an existing requirement.
2. Verify that the :ref:`test suites <testing>` pass with the package version changed on
your local machine before attempting to merge the changes.
1. Identify the package version to modify and consider why you need to change the
required version. If it is a core package used frequently (e.g. ``NumPy``) then
submit an issue to the `Issue Tracker
<https://git.ligo.org/finesse/finesse3/issues>`_ before continuing.
2. Determine the version you want to change the requirement to. This can be a minimum
version, maximum version or pinned at some specific version number.
3. Find the package name in the correct requirements file and modify the version number
and condition to the value determined from the previous step. For example, if the
package is called ``foo`` and the current pinned version is ``v1.1.0`` then the line
in the requirements file will be::
foo == 1.1.0
If you want to change this to a minimum version of ``v1.3.0`` then this line should
be changed to::
foo >= 1.3.0
5. Verify that the test suites pass with the package version changed on your local
machine - see :ref:`testing` - before attempting to merge the changes.
Removing a required package
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Removing a requirement
~~~~~~~~~~~~~~~~~~~~~~
Occasionally, we may want to remove a package from the requirements if it is no longer
used (typically when a better solution to some problem has been found using a new /
existing package). In this case, the process outlined here should be followed for
removing the package.
1. Identify the package to remove and consider why it should be removed. If it is a
large package or involves many source code changes to accommodate it, then submit an
issue to the `Issue Tracker <https://git.ligo.org/finesse/finesse3/issues>`_ before
continuing.
2. Ascertain the category that the requirement falls under - i.e. if it was a package
needed for a feature of |Finesse| itself then it should be removed from the
``requirements.txt`` file.
3. Remove the line containing the package name from the relevant requirements file.
4. Delete the line containing the package name from one of the following data structures
in ``setup.py``:
a. ``REQUIREMENTS`` if it is a core package required to run |Finesse|,
b. ``SETUP_REQUIREMENTS`` if it is a requirement only to build or install |Finesse|,
OR
c. ``EXTRA_REQUIREMENTS`` if it is an optional extra that should not be installed by
default.
1. Follow the steps in the section above for adding new dependencies, but instead find
and delete the dependency in the respective file.
5. Verify that the test suites pass with the package removed from your local machine -
see :ref:`testing` - before attempting to merge the changes.
2. Verify that the :ref:`test suites <testing>` pass with the package version changed on
your local machine before attempting to merge the changes.
......@@ -6,6 +6,8 @@
Contributing to the documentation
=================================
**Source code:** :source:`docs </docs>`
Here we describe the procedure through which to contribute to these |Finesse|
documentation pages and guidelines for conventions and styles to use. The documentation
is built with `Sphinx <http://sphinx-doc.org/>`_ and uses reStructured Text (reST) for
......@@ -351,8 +353,9 @@ The documentation can be built using the Makefile provided within the ``docs``
directory. Run ``make`` with no arguments to print a list of available output formats.
The most common output format is HTML, which can be produced with the command ``make
html``. Note that in order to compile the documentation certain extra dependencies are
required. These are automatically installed when the project is installed in ``dev``
mode, e.g. using ``pip install -e .[dev]``.
required. These are automatically installed when the project is installed in
:ref:`developer mode <how_to_contribute>`. If you wish to install just the dependencies
required for building the documentation, you can use e.g. ``pip install -e .[docs]``.
In order to build the PDF docs (using ``make latexpdf``), you must ensure that a
comprehensive LaTeX package (such as ``texlive``) and a program that provides the
......
......@@ -66,7 +66,7 @@ Your update should then be immediately available from the JupyterLab extension m
Files published to https://npmjs.com are **permanent**; you cannot unpublish a
package more than 24 hours after it was published, so take care.
Visual Studio Code
==================
......@@ -149,6 +149,6 @@ Pygments
========
The Pygments extension is installed along with |Finesse| by defining the
``pygments.lexers`` entry point in :source:`setup.py <../../setup.py>`, so no further
``pygments.lexers`` entry point in :source:`setup.py </setup.py>`, so no further
packaging work needs to be done. The actual extension is defined in
:source:`script/highlighter.py`, and is described there.
......@@ -80,9 +80,10 @@ sections later on.
Replacing `<username>` with your username on the LIGO GitLab server.
5. Install the developer dependencies via pip::
5. Install the project with developer dependencies using a Python packaging tool such as
`pip <https://pip.pypa.io/en/stable/installing/>`__::
pip install -e .[dev]
pip install -e .[test,docs,lint]
6. Install the pre-commit hooks that will check your code for style errors when you
commit::
......
......@@ -5,9 +5,11 @@
Running and writing tests
-------------------------
|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`.
**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`.
.. note::
......@@ -19,7 +21,7 @@ Pytest
`Pytest <https://docs.pytest.org/>`__ is a framework for writing tests and provides a
number of useful features over the standard library's ``unittest``. Pytest strongly
encourages the use of `"fixtures" <https://docs.pytest.org/en/latest/fixture.html>`__
encourages the use of "`fixtures <https://docs.pytest.org/en/latest/fixture.html>`__"
with tests, which are functions which set up test resources to be provided to tests
themselves. Fixtures are often used in |Finesse| testing to set up models, which
individual test functions then check. For more information, refer to the `Pytest
......@@ -31,7 +33,8 @@ Running the tests provided with Finesse
***************************************
Pytest provides a command-line interface (CLI) for executing tests. To run all of the
tests, simply run Pytest:
tests, simply run Pytest (you must have installed |Finesse| in :ref:`developer mode
<how_to_contribute>`):
.. code:: bash
......@@ -39,8 +42,8 @@ tests, simply run Pytest:
.. note::
Pytest is configured in ``/setup.cfg`` to run tests in the ``/tests`` directory by
default.
Pytest is configured in :source:`setup.cfg </setup.cfg>` 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
......
......@@ -12,7 +12,6 @@ instructions for each of them.
.. contents:: Table of Contents
:local:
JupyterLab
==========
......@@ -25,8 +24,9 @@ KatScript, or ``#kat2`` for |Finesse| 2 style KatScript.
:align: center
:width: 80%
You can install the JupyterLab extension either via ``pip`` or the JupyterLab extension
manager. To install via ``pip``::
You can install the JupyterLab extension either via a Python packaging tool such as
`pip <https://pip.pypa.io/en/stable/installing/>`__ or the JupyterLab extension manager.
To install via `pip`, run::
pip install katscript-jupyterlab
......@@ -37,7 +37,6 @@ To install via the JupyterLab extension manager, enable it and search for KatScr
:align: center
:width: 80%
Visual Studio Code
==================
......@@ -57,7 +56,6 @@ You can install the Visual Studio Code extension from the built in extension man
:align: center
:width: 50%
Vim
===
......@@ -73,7 +71,6 @@ KatScript, start the file with the comment ``#kat2``.
You can install the Vim extension using your preferred method of managing extensions
from the `git repository <https://git.ligo.org/finesse/katscript-vim>`_.
Pygments
========
......
......@@ -2,39 +2,71 @@
.. _installation:
Installation
------------
============
For most users we recommend installing the **release version** of |Finesse| as this will
always be the most stable. Any bugs found in release versions can be debugged more
easily than in an arbitrary development version, so subsequent minor releases will
typically address these issues faster.
typically address these issues faster. If however you need some feature or bugfix
that's only available in the latest development version then you can install from
source.
Release version
***************
---------------
|Finesse| 3 is still under active development. There is currently no release version
available. You can find the executables for the stable |Finesse| 2 at:
`<http://www.gwoptics.org/finesse>`_.
|Finesse| 3 is still under active development. There is currently no stable release
version available, though there is an early alpha version available on `PyPI
<https://pypi.org/project/finesse/>`__. It will eventually also be available via Conda.
Via PyPI
~~~~~~~~
The PyPI version can be installed using a Python package manager such as `pip
<https://pip.pypa.io/en/stable/installing/>`__::
pip install finesse
To later update your version of |Finesse|, you can run::
pip install --upgrade finesse
Via Conda
~~~~~~~~~
.. todo:: Document installing Finesse Conda package once available
From source
***********
-----------
.. note::
.. see-also::
If you want to contribute to the development of |Finesse| then you should read
:ref:`dev_get_started` as this will tell you how to set-up a development environment
which is separate to any stable version you may have installed.
If you want to contribute to the *development* of |Finesse| then you should rather
read :ref:`dev_get_started`.
Follow the steps below to install the latest state of |Finesse|. Make sure to follow the
guide corresponding to the system you are installing to.
Follow the steps below for your operating system to install the bleeding edge version of
|Finesse|.
Linux / Mac OSX / WSL
~~~~~~~~~~~~~~~~~~~~~
Via Conda
~~~~~~~~~
`Conda <https://docs.conda.io/en/>`__ is the free and open source package manager
included in the `Anaconda <https://www.anaconda.com/products/individual>`__ and
`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ scientific computing
packages.
Regardless of platform, you need to first install the Conda package manager, either via
`Anaconda <https://www.anaconda.com/products/individual>`__ or `Miniconda
<https://docs.conda.io/en/latest/miniconda.html>`__.
1. If you have not already done so, install the `Conda package manager
<https://docs.conda.io/en/latest/miniconda.html>`_.
Note that in these steps |Finesse| is installed in "editable" mode. This options means
that any changes to Python source code files in the local git copy (i.e. after pulling
the latest changes on master from the repository) will be reflected in the installed
version.
2. Install gcc. If you are on Debian/Ubuntu or similar, install via::
Linux / Mac OSX / WSL
*********************
1. Install ``gcc``. If you are on Debian/Ubuntu or similar, you can install via::
apt-get install build-essential
......@@ -42,7 +74,7 @@ Linux / Mac OSX / WSL
xcode-select --install
3. Clone the repository `<https://git.ligo.org/finesse/finesse3>`_ via HTTPS::
2. Clone the repository `<https://git.ligo.org/finesse/finesse3>`_ via HTTPS::
git clone https://git.ligo.org/finesse/finesse3
......@@ -50,42 +82,37 @@ Linux / Mac OSX / WSL
git clone git@git.ligo.org:finesse/finesse3.git
4. Change directory to your local copy of the |Finesse| repository::
3. Change directory to your local copy of the |Finesse| repository::
cd finesse3
5. Create a new Conda environment using the |Finesse| environment file::
4. Create a new Conda environment using the |Finesse| environment file::
conda env create -n <name_of_environment> -f environment.yml
where you should substitute ``<name_of_environment>`` for a suitable name of your
choice, e.g: ``finesse3``.
6. The above step should automatically activate your new environment, but to make sure
that your shell is using this Conda environment from above run::
5. The above step should install all necessary dependencies and build and install
|Finesse|. Depending on your configuration, Conda may or may not activate your new
environment automatically. If it did not, you can simply run::
conda activate <name_of_environment>
7. Installation of |Finesse| in development mode is now simple, just run::
pip install -e .
in the root directory of your local copy of the |Finesse| repository.
At this point you should see a ``(<name_of_environment>)`` at the start of your shell
prompt, indicating that the environment is active.
Windows
~~~~~~~
1. If you have not already done so, install the `Conda package manager
<https://docs.conda.io/en/latest/miniconda.html>`_.
*******
2. Again, if you have not already done so, install `Git for Windows
1. If you have not already done so, install `Git for Windows
<https://gitforwindows.org/>`_. You can either use the tools this provides directly
to clone the |Finesse| repository (see step 5 below) or add the path to your git
executable to the Windows environment variables - details on how to do this are shown
in the next step, but you can skip this if you intend to use the *git bash/gui here*
feature(s) of Git for Windows.
3. (Optional) To be able to use git from the command line, and via an Anaconda Prompt,
2. (Optional) To be able to use git from the command line, and via an Anaconda Prompt,
you need to add the path to your git executable (installed in the step above) to the
Windows environment variables.
......@@ -103,9 +130,9 @@ Windows
Note that these paths above are assuming that you did not change the default install
location of Git for Windows in step 2.
4. Open an Anaconda Prompt using the Windows search bar.
3. Open an Anaconda Prompt using the Windows search bar.
5. Clone the repository `<https://git.ligo.org/finesse/finesse3>`_ via HTTPS::
4. Clone the repository `<https://git.ligo.org/finesse/finesse3>`_ via HTTPS::
git clone https://git.ligo.org/finesse/finesse3
......@@ -119,42 +146,30 @@ Windows
command above. Close this terminal after cloning the repository and return to your
Anaconda Prompt.
6. Change directory to your local copy of the |Finesse| repository::
5. Change directory to your local copy of the |Finesse| repository::
cd finesse3
7. Create a new Conda environment using the |Finesse| **Windows** environment file::
6. Create a new Conda environment using the |Finesse| **Windows** environment file::
conda env create -n <name_of_environment> -f environment_win.yml
where you should substitute ``<name_of_environment>`` for a suitable name of your
choice, e.g: ``finesse3``.
8. The above step should automatically activate your new environment, but to make sure
that your shell is using this Conda environment from above run::
7. The above step should install all necessary dependencies and build and install
|Finesse|. Depending on your configuration, Conda may or may not activate your new
environment automatically. If it did not, you can simply run::
conda activate <name_of_environment>
9. To build the Cython extensions of |Finesse| you must now run::
make.bat
10. Installation of |Finesse| in development mode is now simple, just run::
pip install -e .
in the root directory of your local copy of the |Finesse| repository.
At this point you should see a ``(<name_of_environment>)`` at the start of your shell
prompt, indicating that the environment is active.
If you encounter any issues here then refer to the troubleshooting guide below.
Note that in the final step of both guides above we use the ``-e`` option with pip
install. This options means that the install is performed in "editable" mode such that
any changes to Python source code files in |Finesse| (i.e. after pulling the latest
changes on master from the repository) will be reflected in a version installed in this
way.
Keeping your development version up to date
*******************************************
-------------------------------------------
If you want to use all the new features of |Finesse| as they are developed then you will