diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..5d15d96 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,41 @@ +# This workflow installs the package and builds the docs +# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions + +name: build the docs + +on: + push: + branches: [ 'main' ] + pull_request: + branches: [ '**' ] + +jobs: + sphinx: + strategy: + matrix: + os: + - ubuntu-latest + python-version: + - '3.8' + + fail-fast: false + + + runs-on: ${{ matrix.os }} + name: ${{ matrix.os }} py${{ matrix.python-version }} + + steps: + - uses: actions/checkout@v2 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies and package for building the docs + run: | + python -m pip install --upgrade pip + pip install --editable .[doc] + + - name: Build the docs + run: make --directory=doc html diff --git a/.gitignore b/.gitignore index b6e4761..78de9bb 100644 --- a/.gitignore +++ b/.gitignore @@ -69,7 +69,7 @@ instance/ .scrapy # Sphinx documentation -docs/_build/ +doc/_build/ # PyBuilder target/ @@ -127,3 +127,10 @@ dmypy.json # Pyre type checker .pyre/ + +# JetBrains IDEs +*.iml +.idea/ + +# Apple file system +.DS_Store diff --git a/README.md b/README.md index 689f8d8..a456efa 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,41 @@ -# python-stub +# A template repo for IIASA Python projects + +Copyright (c) 2021 IIASA + +![GitHub](https://img.shields.io/github/license/iiasa/python-stub) + +## Overview + Template repository for creating python packages and Sphinx-based documentation pages in line with the IIASA design guidelines + +## Configuration + +To start a new Python package from this repo, +click on the green **Use this template** button on top-right of this page. +Detailed instructions to create a new repository from a template can be found +[here](https://help.github.com/en/articles/creating-a-repository-from-a-template). + +Then, make the following changes: + +0. Change the text of the `LICENSE` file and the badge in this readme (optional). +1. Rename the folder `python_stub` to the intended package name. +2. Update the package name, author info and url in `setup.cfg`. +3. Update the package name, author info and copyright in `doc/source/conf.py`. +4. Delete the configuration section from this readme and update the title and overview section. + +Make sure to commit all changes to your new repository - then program away! + +## Installation + +Install the package including the requirements for building the docs. + + pip install -e .[doc] + +## Building the docs + +Navigate to the doc folder and run Sphinx. + + cd doc + make html + +The rendered html pages will be located in `doc/build/html/index.html`. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..a17256f --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,21 @@ +# Minimal makefile for Sphinx documentation +# This file was generated with sphinx-quickstart version 3.5.0 +# + +# 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/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..9fb2e4a --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,37 @@ +REM This file was generated with sphinx-quickstart version 3.5.0 + +@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 diff --git a/doc/source/_static/iiasa.css b/doc/source/_static/iiasa.css new file mode 100644 index 0000000..097100d --- /dev/null +++ b/doc/source/_static/iiasa.css @@ -0,0 +1,77 @@ +/* + +IIASA blue + three-stage gradient to white +- #00589d / #3f81b5 / #7fabce / #bfd5e6 + +IIASA secondary colours + two-stage gradient to white +- #62c5c0 / #96d8d5 / #caebea +- #247f6e +- #fdbb40 +- #ee6a6b +- #6a4c93 + +*/ + +/* Overall backgrounds */ +.wy-nav-side, .wy-side-nav-search, .wy-nav-top { + background: #00589d; +} + +/* White line between search & menu panels */ +.wy-side-nav-search { + border-bottom: 1px solid #ffffff; +} + +/* Text colours of menu items: general */ +.wy-menu-vertical a { + color: #ffffff; +} + +/* …: current items levels 1–3 */ +.wy-menu-vertical li.on a, +.wy-menu-vertical li.current > a, +.wy-menu-vertical li.toctree-l3.current > a { + color: #00589d; +} + +/* …: current item level 4 */ +.wy-menu-vertical li.toctree-l3 > a { + color: #000000; +} + +/* Borders around current items */ +.wy-menu-vertical li.current a { + border-right: 1px solid #00589d; +} + +.wy-menu-vertical li.toctree-l1.current > a { + border-bottom: 1px solid #00589d; + border-right: none; +} + +/* Gradient colouring of sub-menus */ +.wy-menu-vertical li.current, +.wy-menu-vertical li.toctree-l2.current > a { + background: #bfd5e6; /* blue */ +} + + +.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a { + background: #7fabce; /* blue */ +} + +.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a { + background: #3f81b5; /* blue */ + color: #ffffff; +} + +/* Hovered links; all the same colour */ +.wy-menu-vertical li > a:hover, +.wy-menu-vertical li.current > a:hover, +.wy-menu-vertical li.current li.toctree-l2 > a:hover, +.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover, +.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a:hover { + /* white on purple */ + background: #6a4c93; + color: #ffffff; +} diff --git a/doc/source/_static/iiasa_logo_white.png b/doc/source/_static/iiasa_logo_white.png new file mode 100644 index 0000000..583cbab Binary files /dev/null and b/doc/source/_static/iiasa_logo_white.png differ diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..d12a2f3 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,60 @@ +# 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: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- 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 = "python-stub" +copyright = "2021 IIASA" +author = "Daniel Huppmann" + + +# -- 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 = [] + + +# -- 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" + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "_static/iiasa_logo_white.png" + +# 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"] + + +# Add the IIASA stylesheet +def setup(app): + app.add_css_file("iiasa.css") diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..a85c5b8 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,5 @@ +An IIASA Python project +======================= + +This is a template project for an IIASA Python project +with Sphinx documentation pages based on the IIASA design guidelines. \ No newline at end of file diff --git a/python_stub/__init__.py b/python_stub/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..b3d4c62 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,23 @@ +[metadata] +name = python_stub +author = Daniel Huppmann +author_email = huppmann@iiasa.ac.at +description = Template for creating python packages and Sphinx-based docs pages +long_description_content_type = text/markdown +long_description = file:README.md +url = https://www.iiasa.ac.at +# license = (TODO: update this to match the license you choose for the package) + +[options] +packages = python_stub +install_requires = +setup_requires = + setuptools >= 41 + setuptools_scm + +[options.extras_require] +tests = + pytest +doc = + sphinx + sphinx_rtd_theme \ No newline at end of file diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..d5d43d7 --- /dev/null +++ b/setup.py @@ -0,0 +1,3 @@ +from setuptools import setup + +setup(use_scm_version=True)