Make documentation

.readthedocs.yaml

@@ -0,0 +1,21 @@
+version: 2
+
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+  fail_on_warning: false
+
+formats:
+  - htmlzip
+
+python:
+  version: 3.8
+  install:
+    - requirements: requirements-docs.txt
+    - requirements: requirements.txt
+    - method: pip
+      path: .
+  system_packages: false
+
+build:
+  image: latest

.travis.yml

@@ -6,6 +6,23 @@ env:
   matrix:
   - PYTHON="3.8"
 sudo: false
+
+jobs:
+  include:
+  - stage: lint
+    os: linux
+    script:
+    - pip install flake8
+    - make lint
+
+  - stage: docs
+    os: linux
+    install:
+    - pip install -r requirements-docs.txt
+    - pip install -e .
+    script:
+    - make -C docs clean html
+
 before_install:
 - |
   if [[ $TRAVIS_OS_NAME == "osx" ]]; then

CONTRIBUTING.rst

@@ -0,0 +1,131 @@
+.. highlight:: shell
+
+============
+Contributing
+============
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+Types of Contributions
+----------------------
+
+Report Bugs
+~~~~~~~~~~~
+
+Report bugs at https://github.com/csdms/babelizer/issues.
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in troubleshooting.
+* Detailed steps to reproduce the bug.
+
+Fix Bugs
+~~~~~~~~
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
+wanted" is open to whoever wants to implement it.
+
+Implement Features
+~~~~~~~~~~~~~~~~~~
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+Write Documentation
+~~~~~~~~~~~~~~~~~~~
+
+*babelizer* could always use more documentation, whether as part of the
+official *babelizer* docs, in docstrings, or even on the web in blog posts,
+articles, and such.
+
+Submit Feedback
+~~~~~~~~~~~~~~~
+
+The best way to send feedback is to file an issue at https://github.com/csdms/babelizer/issues.
+
+If you are proposing a feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+* Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+Get Started!
+------------
+
+Ready to contribute? Here's how to set up *babelizer* for local development.
+
+1. Fork the *babelizer* repo on GitHub.
+2. Clone your fork locally::
+
+    $ git clone git@github.com:your_name_here/babelizer.git
+
+3. Install your local copy into a conda environment. Assuming you have conda
+   installed, this is how you set up your fork for local development::
+
+    $ conda create -n babelizer python=3.8
+    $ conda activate babelizer
+    $ cd babelizer/
+    $ conda install --file=requirements.txt
+
+    $ python setup.py develop
+
+4. Create a branch for local development::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+   Now you can make your changes locally.
+
+5. When you're done making changes, check that your changes pass flake8 and the
+   tests::
+
+    $ make lint
+    $ make test
+
+   To get flake8, just conda install it into your environment.
+
+6. Commit your changes and push your branch to GitHub::
+
+    $ git add .
+    $ git commit -m "Your detailed description of your changes."
+    $ git push origin name-of-your-bugfix-or-feature
+
+7. Submit a pull request through the GitHub website.
+
+Pull Request Guidelines
+-----------------------
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to the list in README.rst.
+3. The pull request need only work with Python >= 3.8. Check
+   https://travis-ci.org/csdms/babelizer/pull_requests
+   and make sure that the tests pass.
+
+Deploying
+---------
+
+A reminder for the maintainers on how to deploy. To make a new release,
+you will need to have [zest.releaser](https://zestreleaser.readthedocs.io/en/latest/)
+installed, which can be installed with *pip*,
+
+.. code:: bash
+
+    $ pip install zest.releaser[recommended]
+
+Make sure all your changes are committed (including an entry in CHANGES.rst).
+Then run,
+
+.. code:: bash
+
+    $ fullrelease
+
+This will create a new tag and alert the *babelizer* feedstock on
+*conda-forge* that there is a new release.

LICENSE.rst

@@ -0,0 +1,26 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `2020` `Community Surface Dynamics Modeling System`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+

MANIFEST.in

@@ -1,4 +1,3 @@
-include LICENSE
 include *.rst
 include requirements*.txt
 include Makefile

README.rst

@@ -1,6 +1,10 @@
 .. image:: https://img.shields.io/travis/csdms/babelizer.svg
         :target: https://travis-ci.org/csdms/babelizer
 
+.. image:: https://readthedocs.org/projects/babelizer/badge/?version=latest
+        :target: https://babelizer.readthedocs.io/en/latest/?badge=latest
+        :alt: Documentation Status
+
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
         :target: https://github.com/csdms/babelizer
 
@@ -15,8 +19,8 @@ Wrap BMI libraries with Python bindings
 About
 *****
 
-The *babelizer* is a utility for wrapping libraries, from a variety for
-languages, that expose a Basic Model Interface (BMI) so that they can
+The *babelizer* is a utility for wrapping libraries, from a variety of
+languages, that expose a Basic Model Interface (BMI) so that they can be
 imported as a Python package.
 
 
@@ -30,7 +34,7 @@ Supported languages:
 Requirements
 ************
 
-The *babelizer* is Python 3 only.
+The *babelizer* requires Python >=3.8.
 
 
 Apart from Python, the *babelzer* has a number of other requirements, all of which
@@ -52,20 +56,19 @@ Installation
 To install the *babelizer*, first create a new environment in
 which *babelizer* will be installed. This, although not necessary, will
 isolate the installation so that there won't be conflicts with your
-base *Python* installation. This can be done with *conda* as::
+base *Python* installation. This can be done with *conda* as,
+
+.. code:: bash
 
-  $ conda create -n babelizer python=3
-  $ conda activate babelizer
+    $ conda create -n babelizer python=3
+    $ conda activate babelizer
 
 Stable Release
 ==============
 
-The *babelizer*, and its dependencies, can be installed either with *pip*
-or *conda*. Using *pip*::
-
-    $ pip install babelizer
+The *babelizer*, and its dependencies, is best installed with *conda*,
 
-Using *conda*::
+.. code:: bash
 
     $ conda install babelizer -c conda-forge
 
@@ -257,11 +260,15 @@ For example the above *babel.toml* can be generated with the following,
 
 .. code:: bash
 
-  $ babelize generate babel.toml --summary="PyMT plugin for hydrotrend" --entry-point=Hydrotrend=bmi_hydrotrend:register_bmi_hydrotrend --name=hydrotrend --requirement=hydrotrend
+  $ babelize generate babel.toml \
+      --summary="PyMT plugin for hydrotrend" \
+      --entry-point=Hydrotrend=bmi_hydrotrend:register_bmi_hydrotrend \
+      --name=hydrotrend \
+      --requirement=hydrotrend
 
-********
-Examples
-********
+***
+Use
+***
 
 Generate Python bindings for a library that implements a BMI,
 sending output to the current directory
@@ -275,3 +282,10 @@ Update an existing repository
 .. code:: bash
 
   $ babelize update
+
+For a complete example of using the *babelizer*
+to wrap a C library exposing a BMI,
+see the User Guide of the `documentation`_.
+
+
+.. _documentation: https://babelizer.readthedocs.io/

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)

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
+
+if "%1" == "" goto help
+
+%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.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/links.html

@@ -0,0 +1,7 @@
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="https://github.com/csdms/babelizer/">babelizer @ GitHub</a></li>
+  <li><a href="https://github.com/csdms/babelizer/issues">Issue Tracker</a></li>
+  <li><a href="https://csdms.colorado.edu">CSDMS Homepage</a></li>
+</ul>
+

docs/source/_templates/sidebarintro.html

@@ -0,0 +1,6 @@
+<h3>About babelizer</h3>
+<p>
+  The <i>babelizer</i> wraps libraries
+  that expose a Basic Model Interface (BMI)
+  so they can imported as Python packages.
+</p>