Docs, setuptools_scm, changelog, util etc.

Also in setup.cfg: - extra requires [docs], [dev] FIXME: - intersphinx links to Nek5000 documentation - internal autodoc and autosummary
snek5000 · Jan 17, 2020 · 8342d14 · 8342d14
1 parent 2a0cc64
commit 8342d14
Show file tree

Hide file tree

Showing 19 changed files with 296 additions and 44 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -53,8 +53,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install .
+        pip install .[docs]
         if [ ! -d "doxygen-${DOXYGEN_VERSION}" ]; then
           curl -LO http://doxygen.nl/files/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz
           tar -xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz

diff --git a/.gitignore b/.gitignore
@@ -53,8 +53,10 @@ src/*/*.log*
 venv/
 .python-version
 .snakemake
+.eggs
 *.egg-info
 __pycache__
+src/*/_version.py
 
 # Doxygen / Sphinx
 docs/_build
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -1,2 +1,4 @@
+# Authors
+
 * [Ashwin Vishnu Mohanan](mailto:[email protected])
 * [Luigi Antonialli](mailto:[email protected])
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,36 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--
+
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+Type of changes
+---------------
+
+Added for new features.
+Changed for changes in existing functionality.
+Deprecated for soon-to-be removed features.
+Removed for now removed features.
+Fixed for any bug fixes.
+Security in case of vulnerabilities.
+
+-->
+
+## [Unreleased]
+- Paraview I/O for loading and plotting functions
+
+## [0.0.0] - 2020-01-17
+
+### Added
+- Scripting for executing managing run parameters `eturb.params`
+- Python packaging
+- Sphinx + Doxygen + Breathe documentation
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,6 @@
-# General guidelines
+# Developer guide
+
+## General guidelines
 
 
 * **Editor**: Use an editor which supports [EditorConfig](http://editorconfig.org/)

diff --git a/README.md b/README.md
@@ -1,7 +1,8 @@
 # eturb
+
 Efficient simulations of turbulent atmospheric boundary layer.
 
-## Getting started
+## Installation
 
 ```sh
 # Clone
@@ -22,13 +23,24 @@ cd -
 
 ### Easy way
 
+This workflow requires you to setup a python environment. There are two ways to
+do this (and it has to be done only once):
+
+1. Using `venv`
+   ```sh
+   python -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt
+   pip install -e .
+   ```
+2. Using `conda`
+   ```sh
+   conda env create -n eturb -f environment.yml
+   conda activate eturb
+   ```
+
+#### Run Snakemake
 ```sh
-# Setup python environment
-python -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt  # only once
-
-
 # Everything done via a Snakefile at once
 cd src/abl_nek5000/
 snakemake run

diff --git a/docs/AUTHORS.md b/docs/AUTHORS.md
@@ -0,0 +1 @@
+../AUTHORS.md
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -0,0 +1 @@
+../CHANGELOG.md
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1 @@
+../CONTRIBUTING.md
diff --git a/docs/Makefile b/docs/Makefile
@@ -18,3 +18,9 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+intersphinx-python:
+	@python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+
+intersphinx-nek:
+	@python -msphinx.ext.intersphinx https://nek5000.github.io/NekDoc/objects.inv
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,30 +21,62 @@
 from subprocess import PIPE
 
 import breathe
+import eturb
 
-sys.path.insert(0, os.fspath(Path(breathe.__file__).parent))
 
+def root(module):
+    return os.fspath(Path(module.__file__).parent)
+
+
+sys.path.insert(0, root(breathe))
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, root(eturb))
+
+print(sys.path)
 
 # -- Project information -----------------------------------------------------
 
 project = "eturb"
 copyright = "2019, Ashwin Vishnu Mohanan"
 author = "Ashwin Vishnu Mohanan"
 
+version = '.'.join(eturb.__version__.split('.')[:3])
 # The full version, including alpha/beta/rc tags
-release = "0.0.0"
+release = eturb.__version__
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "recommonmark",
+]
 
 # Execute Doxygen
 os.makedirs("_build/html/doxygen", exist_ok=True)
 
+# Inspect whether to run doxygen or not
+last_modified = max(
+    eturb.util.last_modified("../lib").stat().st_mtime,
+    eturb.util.last_modified("../src/abl_nek5000").stat().st_mtime
+)
+timestamp = Path("_build/.doxygen_timestamp")
+if timestamp.exists() and Path("_build/xml").exists():
+    with open(timestamp) as fp:
+        last_documented = float(fp.read())
+    exec_doxygen = last_documented < last_modified
+else:
+    exec_doxygen = True
+
 # Modify Doxygen configuration or not
 modify_doxygen = any(
     os.getenv(env) for env in ("CI", "GITHUB_ACTIONS", "READTHEDOCS")
@@ -63,24 +95,29 @@
     # print(doxy_cfg.decode("utf8"))
 
 
-print("Executing Doxygen... ", end="")
 try:
-    if modify_doxygen:
-        # Pass configuration via stdin
-        with subprocess.Popen(
-            ["doxygen", "-"], stdin=PIPE, stdout=PIPE
-        ) as proc:
-            doxy_output = proc.communicate(input=doxy_cfg)[0]
+    if exec_doxygen:
+        print("Executing Doxygen... ", end="")
+        if modify_doxygen:
+            # Pass configuration via stdin
+            with subprocess.Popen(
+                ["doxygen", "-"], stdin=PIPE, stdout=PIPE
+            ) as proc:
+                doxy_output = proc.communicate(input=doxy_cfg)[0]
+        else:
+            doxy_output = subprocess.check_output(["doxygen"])
+
+        doxy_summary = doxy_output.decode("utf8").splitlines()[-2:]
+        print("done:", *doxy_summary)
+        with open(timestamp, "w") as fp:
+            fp.write(str(last_modified))
     else:
-        doxy_output = subprocess.check_output(["doxygen"])
+        print(f"Using old Doxygen XML output... Remove {timestamp} to force doxygen build.")
 except FileNotFoundError:
     print(
         "Can not find doxygen to generate the documentation of the Fortran code."
     )
 else:
-    doxy_summary = doxy_output.decode("utf8").splitlines()[-2:]
-    print("done:", *doxy_summary)
-
     # -- Breathe configuration ---------------------------------------------------
     extensions.append("breathe")
 
@@ -103,12 +140,17 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -120,3 +162,13 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+# -- Options for Intersphinx -------------------------------------------------
+
+intersphinx_mapping = dict(
+    python=('https://docs.python.org/3', None),
+    nek=('https://nek5000.github.io/NekDoc', None)
+)
+
+# -- Other options ------------------------------------------------------------
+autosummary_generate = True
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,13 +6,42 @@
 Welcome to eturb's documentation!
 =================================
 
++------------+--------------------------------+
+| Repository | https://github.com/exabl/eturb |
++------------+--------------------------------+
+| Version    | |release|                      |
++------------+--------------------------------+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   README
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: User Guide
 
    abl
    nek5000
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Help & Reference
+
+   CONTRIBUTING
+   CHANGELOG
+   AUTHORS
+
+Links
+=====
+
+.. * :ref:`Upstream documentation for Nek5000 <nek:genindex>`
+.. Strange intersphinx bug: WARNING: undefined label: nek:genindex (if the link has no caption the label must precede a section header)
+
+* `Nek5000 documentation <https://nek5000.github.io/NekDoc/appendix.html>`_
+* `KTH framework documentation <https://kth-nek5000.github.io/KTH_Framework>`_
+
 Indices and tables
 ==================
 

diff --git a/lib/Nek5000 b/lib/Nek5000
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,2 @@
+[build-system]
+requires = ["setuptools>=42.0.0", "wheel", "setuptools_scm"]
diff --git a/setup.cfg b/setup.cfg
@@ -1,11 +1,19 @@
 [metadata]
 author = Ashwin Vishnu Mohanan
 author_email = [email protected]
+url = https://exabl.github.io/eturb
 name = eturb
-version = 0.0.1
 description = Python utilities for eturb project
 long_description = file: README.md, HISTORY.md
 long_description_content_type = text/markdown
+license = BSD-3-Clause
+license_file = LICENSE
+classifiers =
+        Development Status :: 2 - Pre-Alpha
+        Intended Audience :: Developers
+        License :: OSI Approved :: MIT License
+        Natural Language :: English
+        Programming Language :: Python :: 3
 
 [options]
 package_dir=
@@ -14,6 +22,35 @@ packages=find:
 install_requires =
     snakemake
     fluiddyn
+setup_requires =
+    setuptools_scm
+
+[options.extras_require]
+docs =
+    sphinx
+    recommonmark
+    sphinx_rtd_theme
+    breathe
+    setuptools_scm
+
+test =
+    pytest
+
+dev =
+    %(docs)s
+    %(test)s
+    ipython
+    flake8
+    twine
+    readme-renderer[md]
 
 [options.packages.find]
 where=src
+
+[options.entry_points]
+setuptools.file_finders =
+    setuptools_scm = setuptools_scm.integration:find_files
+
+# setuptools.finalize_distribution_options =
+#     setuptools_scm = setuptools_scm.integration:infer_version
+
diff --git a/setup.py b/setup.py
@@ -1,4 +1,14 @@
 from setuptools import setup
 
 
-setup()
+# When https://github.com/pypa/setuptools/issues/1055 is fixed
+# this can be moved to setup.cfg
+setup(
+    use_scm_version={
+        'write_to': 'src/eturb/_version.py',
+        'write_to_template': (
+            '"""Autogenerated by setuptools_scm"""\n'
+            '__version__ = "{version}"\n'
+        ),
+    }
+)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		[build-system]
		requires = ["setuptools>=42.0.0", "wheel", "setuptools_scm"]