Skip to content
This repository has been archived by the owner on May 2, 2024. It is now read-only.

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
actions-user committed Apr 11, 2024
1 parent ba97c30 commit 8df8926
Showing 28 changed files with 2,475 additions and 989 deletions.
1 change: 1 addition & 0 deletions _sources/authors.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. mdinclude:: ../AUTHORS.md
1 change: 1 addition & 0 deletions _sources/contributing.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. mdinclude:: ../CONTRIBUTING.md
1 change: 1 addition & 0 deletions _sources/history.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. mdinclude:: ../HISTORY.md
21 changes: 10 additions & 11 deletions _sources/index.rst.txt
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
.. No Errors Test Project documentation master file, created by
sphinx-quickstart on Fri Aug 30 17:07:56 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to No Errors Test Project's documentation!
==================================================
Welcome to Icon Data Processing Incubator's documentation!
===========================================================

.. toctree::
:maxdepth: 2
:caption: Hello World!

:caption: Contents:

readme
installation
usage
modules
contributing
authors
history

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
78 changes: 78 additions & 0 deletions _sources/installation.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
.. highlight:: shell

============
Installation
============

There are two installation types, a production installation, which is static, and a development installation, which is editable.


Preparation
-----------

To install Icon Data Processing Incubator you need a miniconda installation. You can either set up your miniconda installation manually or use the script `tools/setup_miniconda.sh`, which will download and install the latest version of miniconda.


Installation of dependencies
----------------------------

Dependencies are handled by the conda package manager. The goal of this step is to set up a conda environment according to the requirements of Icon Data Processing Incubator. Note that by design, there are some dependencies already when you start developing the package, as the environment includes linters and other development tools.

The dependencies are handled in requirement files. Free installations are based on the `requirements/requirements.yaml` file, where the top-level dependencies of the package are listed. Pinned installations are based on exported environments and stored in the file `requirements/environment.yaml`.

Environments (based on either unpinned or pinned requirements) are handled by the script `tools/setup_env.sh`. The optional flag `-u` stands for unpinned installation:

.. code-block:: console
$ bash tools/setup_env.sh -u
This will create an up-to-date environment that can be exported to `requirements/environment.yaml` with the optional flag `-e` (see below).

You can control the environment name with the flag `-n` and the Python version with `-v`. Run :code:`./tools/setup_env -h` for available options and defaults (incl. mamba support).


Installation of Icon Data Processing Incubator
-----------------------------------------------

After creating and activating your environment by running

.. code-block:: console
$ ./tools/setup_env.sh
$ conda activate icon-data-processing-incubator
in the root folder of icon-data-processing-incubator, type

.. code-block:: console
$ python -m pip install --no-deps .
for a (static) production installation and

.. code-block:: console
$ pip install --no-deps --editable .
for a (editable) development installation.


Maintenance of the environment (for developers)
-----------------------------------------------

If you need to add new first-level dependencies to your package, make sure to include them in `requirements/requirements.yaml`. (Note that pip requirements can be added to these files in the `- pip:` section of the document.) After a (unpinned!) installation, this will change the full dependency tree and you need to export the environment. You can either do this by hand by activating the environment and then running

.. code-block:: console
$ conda env export icon-data-processing-incubator requirements/environment.yaml
or you can reinstall with the setup script from `requirements/requirements.yaml` and directly export the environment with the `-e` flag.

.. code-block:: console
$ ./tools/setup_env -ue
Interaction with Jenkins and Github actions
-------------------------------------------

Your package is always built on a Github actions server upon committing to the main branch. If your code goes into production, pinned production installations must be tested with Jenkins on CSCS machines. Templates may be found in the jenkins/ folder. Contact DevOps to help you set up your pipeline.
6 changes: 6 additions & 0 deletions _sources/modules.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
=======
Modules
=======

.. automodule:: idpi.mutable_number
:members:
1 change: 1 addition & 0 deletions _sources/readme.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. mdinclude:: ../README.md
1 change: 1 addition & 0 deletions _sources/usage.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. mdinclude:: ../USAGE.md
4 changes: 3 additions & 1 deletion _static/alabaster.css
Original file line number Diff line number Diff line change
@@ -419,7 +419,9 @@ table.footnote td {
}

dl {
margin: 0;
margin-left: 0;
margin-right: 0;
margin-top: 0;
padding: 0;
}

Loading

0 comments on commit 8df8926

Please sign in to comment.