Here be docs!

.gitignore

@@ -0,0 +1,136 @@
+# Created by .ignore support plugin (hsz.mobi)
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# 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/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# 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/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+.doctrees
+docs/
+
+.idea/

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    ?= -a
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = docs
+
+# 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)

README.md

@@ -1,2 +1,37 @@
-# Documentation
-IceCI documentation build using Sphinx
+# IceCI Documentation
+[![Documentation Status](https://readthedocs.org/projects/iceci/badge/?version=latest)](https://iceci.readthedocs.io/en/latest/?badge=latest) 
+
+This repository contains the documentation for IceCI project. Documentation is build using the Sphinx project.
+
+The online version of this documentation can be found [here](https://iceci.readthedocs.org)
+
+## Installation and build
+
+Prepare environment:
+
+```shell script
+python3 -m venv venv
+source venv/bin/activate
+```
+
+Install dependencies:
+
+```shell script
+pip install -r requirements.txt
+```
+
+Build:
+
+```shell script
+make html
+```
+
+## Dependencies
+
+ - [Sphinx](https://www.sphinx-doc.org/) 
+ - [Read the Docs theme - sphinx theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/)
+
+
+---
+
+_Kept cool 🧊 by [Icetek](https://icetek.io/)_

readthedocs.yml

@@ -0,0 +1,12 @@
+version: 2
+formats:
+- html
+
+python:
+   version: 3.7
+   install:
+   - requirements: requirements.txt
+
+sphinx:
+  builder: html
+  configuration: source/conf.py

requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme

source/conf.py

@@ -0,0 +1,67 @@
+# 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 = 'IceCI'
+copyright = '2020, Icetek.io'
+author = 'Icetek.io'
+# html_logo = "_static/iceci_logo.png"
+html_logo = "_static/icon-128x128.png"
+html_favicon = "_static/favicon-32x32.png"
+
+# -- 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 = [
+    'sphinx_rtd_theme',
+    # 'sphinxjsondomain'
+]
+
+# 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 = 'nature'
+
+# 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']
+# import guzzle_sphinx_theme
+#
+# html_theme_path = guzzle_sphinx_theme.html_theme_path()
+# html_theme = 'guzzle_sphinx_theme'
+
+# Register the theme as an extension to generate a sitemap.xml
+# extensions.append("guzzle_sphinx_theme")
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'collapse_navigation': False,
+    'navigation_depth': 4
+}

source/index.rst

@@ -0,0 +1,29 @@
+.. IceCI documentation master file, created by
+  sphinx-quickstart on Sun Mar  1 22:19:41 2020.
+  You can adapt this file completely to your liking, but it should at least
+  contain the root `toctree` directive.
+
+Welcome to IceCI's documentation!
+=================================
+
+Welcome to IceCI`s documentation!
+
+.. toctree::
+  :caption: Introduction
+
+  pages/introduction.rst
+  pages/quickstart.rst
+
+.. toctree::
+  :caption: Running IceCI
+
+  pages/installation.rst
+  pages/configuration.rst
+
+.. toctree::
+  :caption: Pipelines
+
+  pages/pipelines/overview.rst
+  pages/pipelines/building.rst
+  pages/pipelines/structure.rst
+  pages/pipelines/environment.rst

source/pages/configuration.rst

@@ -0,0 +1,61 @@
+Configuration
+#############
+
+This guide will show you how can you customize and configure IceCI's installation for your cluster.
+
+.. note::
+  We'll focus on customizing the deploy by modifying the YAML manifests provided in IceCI's repository.
+
+Before we start, clone IceCI's repository so you can make the modifications locally.
+
+.. code-block:: bash
+
+  git clone https://github.com/IceCI/IceCI.git
+
+
+
+Storage config
+--------------
+
+The storage configuration manifests can be found in ``manifests/operator/pvc-storage.yaml``. As you can see, two types of storage are defined - **static** and **dynamic storage**. In the provided installation, the volumes are configured as 1Gi host paths. As mentioned in the :doc:`installation <installation>` page - it will work fine for single node clusters. You might want to change the type and the requested disk space though, depending on the kind of setup you'll be deploying the application in.
+
+The names of the storage PVCs are defined in the environment variables in ``manifests/operator/operator.yaml`` - you can create the PVCs with different names, but remember to update them in the operator configuration.
+
+.. important::
+  The operator isn't the only application making use of those PVCs - keep in mind that the sync app uses them as well! You can find it's manifest in ``manifests/app/sync.yaml``.
+
+
+
+Database config
+---------------
+
+The default IceCI manifests deploy a PostgreSQL instance for persisting pipeline and build data - it can be found in ``manifests/app/postgres.yaml``. If you already have a database up and running that you'd like to use with IceCI, you can simply skip the creation of that DB and configure the applications to use your own. All you have to do is configure the following environment variables in the API and sync apps. Their manifests can be found in ``manifests/app/api.yaml`` and ``manifests/app/sync.yaml``, respectively.
+
+.. code-block:: yaml
+
+  - name: ICECI_DB_USER
+    value: <db_user>
+  - name: ICECI_DB_HOST
+    value: <db_host>
+  - name: ICECI_DB_NAME
+    value: <db_name>
+  - name: ICECI_DB_PASS
+    value: <db_pass>
+  - name: ICECI_DB_PORT
+    value: <db_port>
+  - name: ICECI_DB_DIALECT
+    value: <db_dialect>
+
+
+
+Resource requests and limits
+----------------------------
+
+By default, the applications deployed in the cluster don't have any resources requests nor limits set. You can add them easily by editing the deployment manifests for each of the applications that you decide do deploy in the cluster. You can read more about resource requests and limits in the `Kubernetes documentation <https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/>`_.
+
+
+
+Further reading
+---------------
+
+How that you've got IceCI installed and configured in your cluster, it's time to build some pipelines. If you need a quick refresher on how a basic pipeline is built, you can go back to the :doc:`Quickstart <quickstart>` page or visit one of example repositories, like the `Quickstart example <https://github.com/dandruszak/example-quickstart>`_ or the `Python Flask API example <https://github.com/IceCI/example-python-flask-api>`_. For a more comprehensive guide on how the pipeline configuration files are structured - check out the :doc:`Pipelines <pipelines/overview>` page.