Adding content to the documentation.

Author: pacesm

README.md

@@ -1,21 +1,56 @@
+## VirES for Swarm - Magnetic Models, Coordinates and Other Utilities
 
-
-## Magnetic Model
-
-This repository contains various utilities related to Earth magnetic field
-modelling and spherical harmonics.
+This repository contains various utilities for calculation of Earth magnetic
+field models, magnetic coordinates and other auxiliary variables.
 
 The repository contains following directories:
 
-- `eoxmagmod` - Collection models of the Earth magnetic field - python module
+- `eoxmagmod` - Python package for calculation of the Earth magnetic field,
+  magnetic coordinates, time conversions and other auxiliary variables.
 - `qdipole` - Quasi-Dipole apex coordinates evaluation - Fortran code compiled
   as a shared library (dependency of the `eoxmagmod` package)
 - `libcdf` - [CDF library](https://cdf.gsfc.nasa.gov/) source installation
   (dependency of the `eoxmagmod` package)
 
-### Installation from Sources
+For more details read the [on-line documentation](https://esa-vires.github.io/MagneticModel/)
+
+### Installation
+
+#### Conda Installation
+
+Step in the MagneticModel directory and follow these steps:
+
+1) Build the binary dependencies:
+```
+conda install conda-build
+conda build ./qdipole
+conda build ./libcdf
+conda build purge
+```
+Tested on GNU/Linux. Possibly works on other POSIX systems.
+
+2) Create an new Conda environment and install `eoxmagmod` dependencies
+
+```
+conda env create -n <environment-name> -f conda_env.yaml
+```
+
+3) Install `eoxmagmod` in your new Conda environment:
+```
+conda activate <environment-name>
+pip install ./eoxmagmod
+```
+
+#### Installation from Sources
+
+The installation requires:
+- GCC C compiler
+- GFortran Fortran compiler
+- `make`
 
-#### CDF
+1) Build and install `cdf` library
+
+The CDF build script download sources and builds the [NASA CDF library](https://cdf.gsfc.nasa.gov/)
 
 ```
 $ cd libcdf/
@@ -30,7 +65,7 @@ variable:
 $ make install INSTALLDIR=<install directory>
 ```
 
-#### QDIPOLE
+2) Build and install `qdipole` library
 
 ```
 $ cd qdipole/
@@ -39,44 +74,32 @@ $ make build
 $ sudo make install
 ```
 
-#### EOxMagMod
-Requires QDIPOLE, CDF libraries + NumPy and SpacePy Python packages
-to be installed.
-NumPy and SpacePy can be installed using `pip`.
+By default the ``qdipole`` library is installed in the ``/usr`` system directory.
+To install the library in a custom location use configuration with a custom prefix::
 
 ```
-$ cd eoxmagmod/
-$ python ./setup.py build
-$ sudo python ./setup.py install
+./configure --prefix=<install prefix>
 ```
 
-### Conda installation
-
-The package contains the `conda-build` scripts allowing local conda build and
-installation following this procedure:
+3) Build and install `eoxmagmod` pip dependencies
 
-1) build the binary dependencies:
 ```
-conda install conda-build
-conda build ./qdipole
-conda build ./libcdf
-conda build purge
+pip3 install 'numpy<2'
+pip3 install scipy
+pip3 install 'SpacePy>0.5'
 ```
-Tested on GNU/Linux. Possibly works on other POSIX systems. Does not work on MS
-Windows (primarily because of a missing Fortran compiler).
 
-2) install the `eoxmagmod` in your conda environment:
+4) Finally, install `eoxmagmod` package
+
 ```
-conda activate <target-environment>
-conda install --use-local qdipole cdf
-conda install numpy scipy matplotlib h5py networkx
-conda install gcc_linux-64           # spacepy and eoxmagmod require C compiler
-conda install gfortran_linux-64      # spacepy requires Fortran compiler
-conda deactivate
-conda activate <target-environment>  # re-activation is required to update the environment variables
-pip install spacepy
-pip install ./eoxmagmod
+pip3 install ./eoxmagmod
 ```
 
-The `gfortran_linux-64` and`gcc_linux-64` compilers work on a x86_64 GNU/Linux system.
-Other platforms might provide different compilers.
+### Testing
+
+To test the fresh installation, leave the `MagneticModel` directory and run
+the following command:
+
+```
+python3 -m unittest discover -p '[a-z]*.py' -v eoxmagmod
+```

conda_env.yaml

@@ -0,0 +1,13 @@
+dependencies:
+  - python >=3.11,<3.12
+  - pip
+  - numpy <2
+  - scipy
+  - matplotlib
+  - h5py
+  - conda-forge::c-compiler
+  - conda-forge::fortran-compiler
+  - local::qdipole
+  - local::cdf
+  - pip:
+      - SpacePy >0.5

docs/conf.py

@@ -3,13 +3,11 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
 
 import os
 import inspect
 import shutil
+#import sphinx
 
 try:  # for Sphinx >= 1.7
     from sphinx.ext import apidoc
@@ -20,8 +18,6 @@
     os.getcwd(), os.path.dirname(inspect.getfile(inspect.currentframe()))
 )
 
-print(__location__)
-
 output_dir = os.path.join(__location__, "api")
 module_dir = os.path.join(__location__, "../eoxmagmod/eoxmagmod")
 
@@ -31,32 +27,28 @@
 except FileNotFoundError:
     pass
 
-try:
-    import sphinx
-
-    cmd_line_template = (
-        "sphinx-apidoc --implicit-namespaces -f -o {outputdir} {moduledir}"
-    )
-    cmd_line = cmd_line_template.format(outputdir=output_dir, moduledir=module_dir)
-
-    args = cmd_line.split(" ")
-    if tuple(sphinx.__version__.split(".")) >= ("1", "7"):
-        # This is a rudimentary parse_version to avoid external dependencies
-        args = args[1:]
-
-    apidoc.main(args)
-except Exception as e:
-    print("Running `sphinx-apidoc` failed!\n{}".format(e))
+#try:
+#    args = (
+#        f"sphinx-apidoc --implicit-namespaces -f -o {output_dir} {module_dir}"
+#    ).split(" ")
+#    if tuple(sphinx.__version__.split(".")) >= ("1", "7"):
+#        # This is a rudimentary parse_version to avoid external dependencies
+#        args = args[1:]
+#    apidoc.main(args)
+#except Exception as e:
+#    print("Running `sphinx-apidoc` failed!\n{}".format(e))
 
 
 def setup(app):
     app.add_css_file("css/custom.css")
 
 
-project = 'MagneticModel'
-copyright = '2022, dolezalovat'
-author = 'dolezalovat'
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+project = 'VirES for Swarm - Magnetic Models, Coordinates and Other Utilities'
+copyright = '2022-2024, EOX IT Services GmbH'
+author = 'Martin Pačes, Týna Doležalova'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -72,7 +64,7 @@ def setup(app):
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
-    "myst_parser",
+    #"myst_parser",
     "sphinx_rtd_theme",
     "sphinx-jsonschema",
     "frigate.sphinx.ext",
@@ -85,7 +77,7 @@ def setup(app):
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
-html_static_path = ["static"]
+#html_static_path = ["static"]
 
 source_suffix = {
     ".rst": "restructuredtext",

docs/index.rst

@@ -1,27 +1,26 @@
-.. MagneticModel documentation master file, created by
-   sphinx-quickstart on Mon Oct 24 10:55:30 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to eoxmagmod documentation!
-===================================
+.. include:: introduction.rst
 
-The ``eoxmagmod``_ library collects low-level subroutines employed
-by the `VirES for Swarm`_ service to calculate:
-
-- geomagnetic models (Spherical Harmonic expansion)
-- magnetic coordinates (quasi-dipole and dipole latitude and longitude, magnetic local time)
-- coordinate system conversions (geodetic, geocentric spherical, geocentric Cartesian coordinates)
-- time conversions (modified Julian date 2000, decimal year)
-- and perform other auxiliary calculations.
+.. toctree::
+  :hidden:
+  :caption: VirES for Swarm
 
-.. _VirES for Swarm: https://vires.service
-.. _eoxmagmod: https://vires.service
+  Git Repository <https://github.com/ESA-VirES/MagneticModel>
+  VirES for Swarm Service <https://vires.services>
+  Swarm Virtual Research Environment (JupyterHub) <https://vre.vires.services>
+  Example Swarm Notebooks <https://notebooks.vires.services>
+  VirES Python Client Documentaion <https://viresclient.readthedocs.io>
 
 .. toctree::
    :maxdepth: 2
+.. toctree::
+  :hidden:
+  :caption: Package Documentation
+
+  Installation <installation>
+  License <license>
 
-   Module Reference <api/modules>
+..   Module Reference <api/modules>