Merge branch 'master' into testing

.github/workflows/tests.yaml

@@ -20,38 +20,59 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup system
+        run: |
+          sudo apt-get install libnetcdff-dev netcdf-bin gfortran gcc
+
       - name: Get SOCRATES
         uses: actions/checkout@v4
         with:
           repository: 'FormingWorlds/SOCRATES'
           path: 'SOCRATES'
 
-      - name: Setup system
-        run: |
-          sudo apt update
-          sudo apt-get install libnetcdff-dev netcdf-bin gfortran gcc
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+      - uses: actions/cache@v3
+        id: cache-socrates
         with:
-          python-version: ${{ matrix.python-version }}
+          path: |
+            SOCRATES/bin
+            SOCRATES/sbin
+            SOCRATES/set_rad_env
+          key: socrates-${{ hashFiles('SOCRATES/version') }}
 
       - name: Build SOCRATES
+        if: steps.cache-socrates.outputs.cache-hit != 'true'
         run: |
           export LD_LIBRARY_PATH=""
           cd SOCRATES
           ./configure
           ./build_code 
-          source set_rad_env
           cd ..
 
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: actions/cache@v3
+        id: cache-virtualenv
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}
+
       - name: Build JANUS
+        if: steps.cache-virtualenv.outputs.cache-hit != 'true'
         run: |
           python -m pip install -e .[develop]
 
+      - uses: actions/cache@v3
+        id: cache-fwl-data
+        with:
+          path: /home/runner/work/fwl_data
+          key: fwl-data-1
+
       - name: Test with pytest
         run: |
-          export FWL_DATA="~/fwl_data"
+          export FWL_DATA="/home/runner/work/fwl_data"
           source SOCRATES/set_rad_env
           coverage run -m pytest
 

.gitignore

@@ -29,5 +29,7 @@ src/janus/data/spectral_files/sp_b318_HITRAN_a16_2203
 
 output/
 utils/*.ipynb*
-fwl_data
-.coverage
+.coverage
+build/
+fwl_data*/
+dist/

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - method: pip
+     path: .
+     extra_requirements:
+      - docs

CONTRIBUTING.md

@@ -1,5 +1,23 @@
 # Contributing guidelines
 
+## Development
+
+### Building the documentation
+
+The documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/), and uses [mkdocs](https://www.mkdocs.org/) to generate the pages.
+
+To build the documentation for yourself:
+
+```console
+pip install -e .[docs]
+mkdocs serve
+```
+
+You can find the documentation source in the [docs](https://github.com/FormingWorlds/JANUS/tree/main/docs) directory.
+If you are adding new pages, make sure to update the listing in the [`mkdocs.yml`](https://github.com/FormingWorlds/JANUS/blob/main/mkdocs.yml) under the `nav` entry.
+
+The documentation is hosted on [readthedocs](https://readthedocs.io/projects/fwl-janus).
+
 ### Running tests
 
 JANUS uses [pytest](https://docs.pytest.org/en/latest/) to run the tests. You can run the tests for yourself using:

README.md

@@ -1,3 +1,4 @@
+[![Documentation Status](https://readthedocs.org/projects/fwl-janus/badge/?version=latest)](https://fwl-janus.readthedocs.io/en/latest/?badge=latest)
 ![Coverage](https://gist.githubusercontent.com/stefsmeets/99391a66bb9229771504c3a4db611d05/raw/covbadge.svg)
 
 ## JANUS (1D convective atmosphere model)
@@ -28,25 +29,28 @@ https://proteus-code.readthedocs.io
 
 ### Developer installation instructions
 1. Download and install Socrates
-    * `git clone [email protected]:FormingWorlds/SOCRATES.git`
-    * `cd SOCRATES`
-    * `./configure`
-    * `./build-code`
-    * `source set_rad_env`
-    * `cd ..`
+```console
+git clone [email protected]:FormingWorlds/SOCRATES.git
+cd SOCRATES
+./configure
+./build-code
+source set_rad_env
+cd ..
+```
 2. Download and install Janus
-    * `git clone [email protected]:FormingWorlds/JANUS.git`
-    * `cd JANUS`
-    * `pip install -e .`
+```console
+git clone [email protected]:FormingWorlds/JANUS.git
+cd JANUS
+pip install -e .
+```
 3. Download data from the [OSF repository](https://osf.io/vehxg/)
     * Set the environment variable FWL_DATA to define where the spectral data files will be stored
         * `export FWL_DATA=...`
-    * Run the following commands within a python environment (or script) to download all basic data
-        * `from janus.utils.data import *`
-        * `DownloadSpectralFiles()`
-        * `DownloadStellarSpectra()`
+    * Run the following commands to download all basic data
+        * `janus download spectral`
+        * `janus download stellar`
     * Alternatively, you can specify which spectral data you want to download, and optionally the number of bands
-    * `DownloadSpectralFiles("/Frostflow", 4096)`
+        * `janus download spectral /Frostflow 4096`
 
 ### Run instructions
 In the examples folder you can find python scripts showing typical usecases/workflows of atmosphere modelling with Janus.

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+{!../CODE_OF_CONDUCT.md!}

docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+{!../CONTRIBUTING.md!}

docs/getting_started.md

@@ -0,0 +1,8 @@
+This page shows you how to get started using JANUS.
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

docs/index.md

@@ -0,0 +1 @@
+{!../README.md!}

mkdocs.yml

@@ -0,0 +1,67 @@
+site_name: JANUS
+site_url: https://fwl-janus.readthedocs.io
+repo_url: https://github.com/FormingWorlds/JANUS
+repo_name: GitHub
+
+nav:
+  - Home: index.md
+  - Getting started: getting_started.md
+  - Contributing: CONTRIBUTING.md
+  - Code of Conduct: CODE_OF_CONDUCT.md
+  - 🔗 Source code: https://github.com/FormingWorlds/JANUS
+  - 🔗 Issues: https://github.com/FormingWorlds/JANUS/issues
+
+theme:
+  name: material
+  palette:
+    primary: black
+    accent: deep orange
+
+extra_css:
+  - stylesheets/extra.css
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - markdown_include.include:
+      base_path: docs
+  - pymdownx.extra
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+plugins:
+- search
+- mkdocstrings:
+    # https://mkdocstrings.github.io/usage/
+    handlers:
+      python:
+        paths: [src]
+        import:
+        - https://installer.readthedocs.io/en/stable/objects.inv
+        - https://numpy.org/doc/stable/objects.inv
+        - https://docs.scipy.org/doc/scipy/objects.inv
+        - https://pandas.pydata.org/docs/objects.inv
+        - https://matplotlib.org/stable/objects.inv
+        options:
+          docstring_style: numpy
+          docstring_options:
+            ignore_init_summary: yes
+          show_submodules: no
+          show_source: true
+          show_root_heading: false
+          show_root_full_path: false
+          docstring_section_style: list
+          members_order: alphabetical
+          merge_init_into_class: yes
+          filters: ["!^_"]
+
+watch:
+  - src/
+  - docs/
+  - README.md
+  - CONTRIBUTING.md
+  - CODE_OF_CONDUCT.md

pyproject.toml

@@ -27,6 +27,7 @@ classifiers = [
 keywords = ["exoplanet", "atmosphere"]
 requires-python = '>=3.10'
 dependencies = [
+  'click',
   'matplotlib',
   'natsort',
   'netcdf4',
@@ -50,12 +51,21 @@ develop = [
   "coverage[toml]",
   "pytest"
 ]
+docs = [
+    "markdown-include",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
 publishing = [
   "twine",
   "wheel",
   "build"
 ]
 
+[project.scripts]
+janus = "janus.cli:cli"
+
 [tool.setuptools]
 package-dir = {"janus" = "src/janus"}
 include-package-data = true

src/janus/cli.py

@@ -0,0 +1,41 @@
+import click
+
+@click.group()
+def cli():
+    pass
+
+@click.group()
+def download():
+    """Download data and dependencies"""
+    pass
+
+@click.command()
+@click.option('-n', '--name', 'fname', type=str, help='Name of the spectra')
+@click.option('-b', '--band', 'nband', type=int, help='Number of the band', default=256)
+def spectral(**kwargs):
+    """Download spectral files
+
+    By default, download all files.
+    """
+    from .utils.data import DownloadSpectralFiles
+    DownloadSpectralFiles(**kwargs)
+
+@click.command()
+def stellar():
+    """Download stellar spectra"""
+    from .utils.data import DownloadStellarSpectra
+    DownloadStellarSpectra()
+
+@click.command()
+def socrates():
+    """Download SOCRATES code"""
+    raise NotImplementedError
+
+
+cli.add_command(download)
+download.add_command(spectral)
+download.add_command(stellar)
+download.add_command(socrates)
+
+if __name__ == '__main__':
+    cli()