Bump version to 0.1.0

.drone.yml

@@ -30,6 +30,19 @@ steps:
   - black --check src tests setup.py
   - flake8
 
+---
+kind: pipeline
+name: docs
+
+steps:
+- name: tests
+  image: python:3.6
+  commands:
+  # Install pre-requisites
+  - pip install -r requirements-dev.txt
+  # Perform linting
+  - doc8
+
 ---
 kind: pipeline
 name: publish

.gitignore

@@ -1,18 +1,110 @@
-venv/
-
-*.pyc
+# Byte-compiled / optimized / DLL files
 __pycache__/
+*.py[cod]
+*$py.class
 
-instance/
+# C extensions
+*.so
 
-.pytest_cache/
-.coverage
-htmlcov/
-
-dist/
+# Distribution / packaging
+.Python
 build/
-*.egg-info/
+develop-eggs/
+dist/
+downloads/
+eggs/
 .eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+pip-wheel-metadata/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
 
 .vscode
-.history
+
+# Ignore any public html content
+sample/public/

.readthedocs.yml

@@ -0,0 +1,7 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: 3.6

README.rst

@@ -6,14 +6,30 @@
   :target: https://codecov.io/gh/shouptech/humulus
   :alt: Code Coverage
 
+.. image:: https://readthedocs.org/projects/humulus/badge/?version=latest
+  :target: https://humulus.readthedocs.io/en/latest/?badge=latest
+  :alt: Documentation Status
+
+.. image:: https://badge.fury.io/py/humulus.svg
+  :target: https://badge.fury.io/py/humulus
+  :alt: PyPi version
+
 Humulus
 =======
 
-Humulus is an open-source homebrew beer recipe webapp built using Flask_ and CouchDB_.
+Humulus is an open-source homebrew beer recipe webapp built using Flask_ and
+CouchDB_.
 
 .. _Flask: http://couchdb.apache.org/
 .. _CouchDB: http://flask.pocoo.org/
 
+Documentation
+-------------
+
+For help installing and using Humulus, please visit the documentation_.
+
+.. _documentation: https://humulus.shoup.io/
+
 License
 -------
 

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     = .
+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/conf.py

@@ -0,0 +1,56 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "humulus"
+copyright = "2019, Mike Shoup"
+author = "Mike Shoup"
+
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+
+# -- 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 = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# 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"]
+
+# Master document
+master_doc = "index"
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# 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"]

docs/contributing.rst

@@ -0,0 +1,70 @@
+Contributing
+============
+
+Humulus has been a personal project of mine, and I hope others will find it
+useful. As a user and fan of open source, I welcome all contributions!
+
+This guide is intended to help you contribute to this project with minimal
+fuss. Please always feel free to open an issue to ask questions!
+
+Issues
+------
+
+Do not hesitate to open issues if you have questions on how to use Humulus, or
+if you think you've found a bug. Please provide any information that you may
+find relevant.
+
+Pull Requests
+-------------
+
+I welcome all pull requests!
+
+For all pull requests, I ask the following:
+
+1. Your pull request should address an open issue. If you'd like to contribute
+   an enhancement, please open an issue first, describing what you'd like to
+   accomplish.
+2. Your code should pass all tests.
+3. Your code should not decrease coverage of the tests.
+4. Your code must have been passed through Black_. The ``pyproject.yml`` file
+   is configured to limit line lengths to 79 characters.
+5. Your code must pass the Flake8_ checks and your documentation must pass the
+   doc8_ checks.
+6. Your code should work with Python 3.6 and newer.
+7. You agree to license your contribution under the `Apache 2.0 License`_. You
+   retain your copyright. Add a copyright notice to the top of the file.
+
+.. _Black: https://black.readthedocs.io/en/stable/
+.. _Flake8: http://flake8.pycqa.org/en/latest/
+.. _doc8: https://github.com/PyCQA/doc8
+.. _`Apache 2.0 License`: https://www.apache.org/licenses/LICENSE-2.0
+
+
+Build environment
+-----------------
+
+All requirements for developing this project are in the
+``requirements-dev.txt`` file. Also, use `pre-commit`_ to help ensure your code
+will pass the linting process.
+
+::
+
+    pip install -r requirements-dev.txt
+    pre-commit install
+
+.. _`pre-commit`: https://pre-commit.com/
+
+Coverage tests
+--------------
+
+Run your code through coverage tests and make sure it passes. Humulus uses
+pytest_ and Coverage.py_ to run tests. If you're contributing new code, please
+add your own tests.
+
+::
+
+    coverage run -m pytest
+    coverage report -m
+
+.. _pytest: https://pytest.org/en/latest/
+.. _Coverage.py: https://coverage.readthedocs.io/en/v4.5.x/

docs/index.rst

@@ -0,0 +1,24 @@
+Humulus
+=======
+
+Humulus is an open-source homebrew beer recipe webapp built using Flask_ and
+CouchDB_.
+
+.. _Flask: http://couchdb.apache.org/
+.. _CouchDB: http://flask.pocoo.org/
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installing
+   contributing
+
+
+License
+-------
+
+Humulus is licensed under the `Apache Version 2.0 license`_.
+
+.. _`Apache Version 2.0 license`: LICENSE

docs/installing.rst

@@ -0,0 +1,164 @@
+Installing
+==========
+
+Docker
+------
+
+It is recommended to install Humulus using docker. You can run a container for
+CouchDB and a container for Humulus on the same machine. Docker makes it easy
+to update to the latest version.
+
+The following commands can be ran to setup Humulus in docker:
+
+::
+
+    # Create a network for all of this to run under
+    sudo docker network create humulus
+
+    # Create a CouchDB container with admin user credentials admin/password
+    sudo docker run -d -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password \
+      --network humulus --name couchdb couchdb:latest
+    # Create the databases needed to run in single server mode
+    sudo docker exec -it couchdb /usr/bin/curl \
+      -X PUT http://admin:password@127.0.0.1:5984/_users
+    sudo docker exec -it couchdb /usr/bin/curl \
+      -X PUT http://admin:password@127.0.0.1:5984/_replicator
+    sudo docker exec -it couchdb /usr/bin/curl \
+      -X PUT http://admin:password@127.0.0.1:5984/_global_changes
+
+    # Create a config file for humulus
+    sudo mkdir -p /opt/humulus
+    sudo tee /opt/humulus/settings.py <<EOF
+    SECRET_KEY = "$(uuidgen -r)"
+    COUCH_URL = "http://couchdb:5984"
+    COUCH_USERNAME = "admin"
+    COUCH_PASSWORD = "password"
+    COUCH_DATABASE = "humulus"
+    HUMULUS_PASSWORD = "foobar"
+    EOF
+    # Run a container for humulus
+    sudo docker run -d -e HUMULUS_SETTINGS=/app/settings.py \
+      --mount type=bind,source=/opt/humulus/settings.py,destination=/app/settings.py,ro \
+      -p 8000:8000 --network humulus --name humulus shouptech/humulus:latest
+
+    # Setup the database and import BJCP styles
+    sudo docker exec -it \
+      -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
+      flask build-couch
+    sudo docker exec -it \
+      -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
+      flask import-styles
+
+After doing the above, point your web browser to http://localhost:8000. Login
+with the password configured for ``HUMULUS_PASSWORD``. Now get to work creating
+recipes.
+
+
+Configuration
+-------------
+
+When launching Humulus, you must point an environment variable,
+``HUMULUS_SETTINGS``, to a python file containing configuration variables.
+
+The following variables must be defined:
+
+``SECRET_KEY``
+^^^^^^^^^^^^^^
+
+The key used to cryptographically sign session cookies. See the
+`Flask documentation for sessions`_.
+
+**Example**: ``b'_5#y2L"F4Q8z\n\xec]/'``
+
+.. _`Flask documentation for sessions`: https://flask.palletsprojects.com/en/1.1.x/quickstart/#sessions
+
+``COUCH_URL``
+^^^^^^^^^^^^^
+
+The URL to find a `CouchDB`_ server at.
+
+**Example**: ``http://couchdb:5984``
+
+.. _`CouchDB`: http://couchdb.apache.org/
+
+``COUCH_USERNAME``
+^^^^^^^^^^^^^^^^^^
+
+The username to connect to CouchDB with.
+
+**Example**: ``admin``
+
+``COUCH_PASSWORD``
+^^^^^^^^^^^^^^^^^^
+
+The password to connect to CouchDB with.
+
+**Example**: ``password``
+
+``COUCH_DATABASE``
+^^^^^^^^^^^^^^^^^^
+
+The CouchDB database to connect to. If the database does not exist, and the
+user defined in ``COUCH_USERNAME`` has permission, the database will be created
+while executing the ``build-couch`` command.
+
+**Example**: ``humulus``
+
+``HUMULUS_PASSWORD``
+^^^^^^^^^^^^^^^^^^^^
+
+The password used for logging into the application. You cannot create, modify,
+or, delete recipes if you're not logged in with this password.
+
+**Example**: ``password``
+
+
+Command Line Interface
+----------------------
+
+The following commands can be executed using the `Flask CLI`_. To execute the
+commands, you must set the environment variable, ``FLASK_APP`` to ``humulus``,
+and set ``HUMULUS_SETTINGS`` to the file created. See `Configuration`_.
+
+.. _`Flask CLI`: https://flask.palletsprojects.com/en/1.1.x/cli/
+
+``build-couch``
+^^^^^^^^^^^^^^^
+
+Used to initialize the Couch database. This command creates the database if not
+found, and also updates any views that are missing, and/or, out of date.
+
+::
+
+    export FLASK_APP=humulus
+    export HUMULUS_SETTINGS=/path/to/settings.py
+    flask build-couch
+
+``import-styles``
+^^^^^^^^^^^^^^^^^
+
+Imports the 2015 BJCP style guidelines. Retrieves a `styleguide.xml`_ from
+GitHub and then writes the data to the Couch database.
+
+::
+
+    export FLASK_APP=humulus
+    export HUMULUS_SETTINGS=/path/to/settings.py
+    flask import-styles
+
+.. _`styleguide.xml`: https://github.com/meanphil/bjcp-guidelines-2015/blob/master/styleguide.xml
+
+Commands in Docker
+^^^^^^^^^^^^^^^^^^
+
+If you're running Humulus using `Docker`_ (the recommended way), you can
+execute the commands inside the docker container:
+
+::
+
+    sudo docker exec -it \
+      -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
+      flask build-couch
+    sudo docker exec -it \
+      -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
+      flask import-styles

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=.
+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

requirements-dev.txt

@@ -3,4 +3,7 @@ coverage
 pre-commit
 black
 flake8
+sphinx-click
+sphinx_rtd_theme
+doc8
 -e .

setup.cfg

@@ -9,10 +9,15 @@ branch = True
 source = humulus
 
 [flake8]
-exclude = .svn,CVS,.bzr,.hg,.git,__pycache__,.tox,.eggs,*.egg,instance
+exclude = .git,__pycache__,.tox,.eggs,*.egg,instance
 show-source = True
 count = True
 max-line-length = 79
 max-complexity = 18
 ignore = W503
 select = B,C,E,F,W,T4,B9
+
+[doc8]
+max-line-length = 79
+extension = .rst
+ignore-path = docs/_build,pip-wheel-metadata,.git,__pycache__,.tox,.eggs,*.egg,src/*.egg-info,instance

src/humulus/_version.py

@@ -14,4 +14,4 @@
 
 # The 'dev' portion of this variable will get updated during Drone CI builds
 # with a build number for all non-tagged builds.
-__version__ = "0.1.dev"
+__version__ = "0.1.0"