Developer workflow now is fast and easy to configure using Poetry and…

… tox. (#11) * Rename pyBL to pybl. * Rename pyBL to pybl * Rename pyBL to pybl * Use poetry now. New requirements.txt config file * Autogenerate documentation setting. * Rename readthedocs.yaml file. * Update .readthedocs.yaml * Add dev dependencies. * Change theme when build on RTD. * Removing src structure. * README not use rst format * First simple version of unfinished docs generation. * Rename Readme.md and src. * Remove legacy code. * Add pre-commit. * Formatted source script and test script. * Update Docs. * Use Poetry to replace setuptools. * New tox env that build docs using sphinx. * Fix EOF of all these file. * Use another option to build docs. * Simple but thorough installation for developers.
NTU-CompHydroMet-Lab · Nov 24, 2023 · e7207f7 · e7207f7
1 parent ca3844f
commit e7207f7
Show file tree

Hide file tree

Showing 85 changed files with 1,840 additions and 300,803 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -10,9 +10,9 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.9', '3.10', '3.11']
+
 
-
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python-version }}
@@ -24,4 +24,4 @@ jobs:
           python -m pip install --upgrade pip
           pip install tox tox-gh-actions
       - name: Test using tox
-        run: tox
+        run: tox
diff --git a/.gitignore b/.gitignore
@@ -161,4 +161,4 @@ cython_debug/
 #.idea/
 
 .vscode/
-examples/*.prof
+examples/*.prof
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,12 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.3.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: https://github.com/psf/black
+    rev: 22.10.0
+    hooks:
+    -   id: black
+        language_version: python3
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,15 +1,18 @@
 version: 2
 
+formats:
+  - pdf
+  - htmlzip
+
 sphinx:
-  configuration: docs/conf.py
+  configuration: docs/source/conf.py
 
 build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
 
 python:
-  version: 3.11
   install:
     - requirements: requirements.txt
     - requirements: requirements-dev.txt

diff --git a/README.md b/README.md
diff --git a/README.rst b/README.rst
@@ -0,0 +1,16 @@
+What is pyBL?
+=============
+
+An implementation of Bartlett-Lewis Model
+
+.. image:: https://github.com/KilinW/pyBL/actions/workflows/tests.yml/badge.svg
+   :target: https://github.com/KilinW/pyBL/actions/workflows/tests.yml
+
+Installation
+============
+
+This package hasn't finished development. If you would like to try, you can install it via test.pypi using this command:
+
+.. code-block:: bash
+
+    $ pip install --extra-index-url https://test.pypi.org/simple/ pyBL
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt
@@ -0,0 +1,2 @@
+# Requirements for building documentation
+furo
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# 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 sys
+
+sys.path.insert(0, os.path.abspath("../../pybl"))
+
+on_rtd = os.environ.get("READTHEDOCS") == "True"
+
+project = "pyBL"
+copyright = "2023, KilinWei"
+author = "KilinWei"
+release = "0.0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+master_doc = "index"
+
+html_theme = "furo"
+html_static_path = ["_static"]
diff --git a/docs/source/developer_guide/build_the_doc.rst b/docs/source/developer_guide/build_the_doc.rst
@@ -0,0 +1,4 @@
+.. _build_the_doc:
+
+Building Documentation
+======================
diff --git a/docs/source/developer_guide/contribute_guideline.rst b/docs/source/developer_guide/contribute_guideline.rst
@@ -0,0 +1,50 @@
+.. _contribute_guideline:
+
+Contributing to pybl
+====================
+
+Preqrequisites
+--------------
+- Python 3.10 or higher
+- Poetry
+
+Setup
+-----
+- **Install Poetry**
+
+You can install poetry by following the instructions on their website: https://python-poetry.org/docs/#installation
+We recommend using poetry to install all the dependencies, as it will also create a virtual environment for you.
+
+- **Clone the repository**
+
+Clone the repository to your local machine using git:
+
+.. code-block:: bash
+
+    git clone https://github.com/NTU-CompHydroMet-Lab/pyBL.git
+
+- **Install dependencies**
+
+Install the dependencies using poetry:
+
+.. code-block:: bash
+
+    poetry install
+
+- **Test if everything works**
+
+.. code-block:: bash
+
+    tox
+
+If everything works, you should see something like this:
+
+.. code-block:: bash
+
+    py39: OK (5.51=setup[2.39]+cmd[3.12] seconds)
+    py310: OK (4.49=setup[1.60]+cmd[2.89] seconds)
+    py311: OK (5.32=setup[1.91]+cmd[3.41] seconds)
+    ruff: OK (1.54=setup[1.52]+cmd[0.03] seconds)
+    mypy: OK (2.91=setup[1.54]+cmd[1.36] seconds)
+    docs: OK (4.20=setup[1.57]+cmd[2.63] seconds)
+    congratulations :) (24.02 seconds)
diff --git a/docs/source/developer_guide/packaging.rst b/docs/source/developer_guide/packaging.rst
@@ -0,0 +1,4 @@
+.. _packaging:
+
+Packaging pybl
+==============
diff --git a/docs/source/developer_guide/test_pybl.rst b/docs/source/developer_guide/test_pybl.rst
@@ -0,0 +1,4 @@
+.. _test_pybl:
+
+Testing pybl
+============
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,42 @@
+.. pybl documentation master file, created by KilinWei
+
+Welcome to pybBL's documentation!
+=================================
+
+pyBL is an open-source Python package for stochastic rainfall modelling based upon the randomised Bartlett-Lewis (BL) rectangular pulse model.
+The BL model is a type of stochastic model that represents rainfall using a Poisson cluster point process.
+This package implements the most recent version of the BL model, based upon the state-of-the-art BL model developed in Onof and Wang (2020).
+
+**Features:**
+
+- Optimized data structure and algorithms for performance.
+- Loosely coupled components for easy extension for specific needs.
+- User-friendly interface for anyone to use.
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: For Users:
+
+   Installation <user_guide/installation>
+   API Reference <pybl_reference/index>
+   Configuration <user_guide/configuring>
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: For developers:
+
+   Contributing <developer_guide/contribute_guideline.rst>
+   Testing <developer_guide/test_pybl.rst>
+   Building Docs <developer_guide/build_the_doc.rst>
+   Packaging <developer_guide/packaging.rst>
diff --git a/docs/source/pybl_reference/index.rst b/docs/source/pybl_reference/index.rst
@@ -0,0 +1,11 @@
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+    :caption: API reference:
+
+    pybl.models
+    pybl.timeseries
+    pybl.raincell
diff --git a/docs/source/pybl_reference/modules.rst b/docs/source/pybl_reference/modules.rst
@@ -0,0 +1,7 @@
+pybl
+====
+
+.. toctree::
+   :maxdepth: 4
+
+   pybl
diff --git a/docs/source/pybl_reference/pybl.models.rst b/docs/source/pybl_reference/pybl.models.rst
@@ -0,0 +1,29 @@
+pybl.models package
+===================
+
+Submodules
+----------
+
+pybl.models.basemodel module
+----------------------------
+
+.. automodule:: pybl.models.basemodel
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pybl.models.blrprx module
+-------------------------
+
+.. automodule:: pybl.models.blrprx
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pybl.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/pybl_reference/pybl.raincell.rst b/docs/source/pybl_reference/pybl.raincell.rst
@@ -0,0 +1,21 @@
+pybl.raincell package
+=====================
+
+Submodules
+----------
+
+pybl.raincell.rcimodel module
+-----------------------------
+
+.. automodule:: pybl.raincell.rcimodel
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pybl.raincell
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/pybl_reference/pybl.rst b/docs/source/pybl_reference/pybl.rst
@@ -0,0 +1,21 @@
+pybl package
+============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   pybl.models
+   pybl.raincell
+   pybl.timeseries
+   pybl.utils
+
+Module contents
+---------------
+
+.. automodule:: pybl
+   :members:
+   :undoc-members:
+   :show-inheritance:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Requirements for building documentation
		furo