From d74ca5b780b83ee457526ba44e601caef3350135 Mon Sep 17 00:00:00 2001 From: Christophe Mehay Date: Fri, 29 Apr 2016 02:33:43 +0200 Subject: [PATCH] Doc --- .gitignore | 93 +++++++++++++ .pre-commit-config.yaml | 2 +- docs/Makefile | 230 +++++++++++++++++++++++++++++++ docs/conf.py | 293 ++++++++++++++++++++++++++++++++++++++++ docs/config.rst | 221 ++++++++++++++++++++++++++++++ docs/extra.rst | 7 + docs/index.rst | 44 ++++++ docs/installation.rst | 34 +++++ docs/templates.rst | 94 +++++++++++++ setup.py | 71 +++++----- 10 files changed, 1054 insertions(+), 35 deletions(-) create mode 100644 .gitignore create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/config.rst create mode 100644 docs/extra.rst create mode 100644 docs/index.rst create mode 100644 docs/installation.rst create mode 100644 docs/templates.rst diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d543650 --- /dev/null +++ b/.gitignore @@ -0,0 +1,93 @@ + +# Created by https://www.gitignore.io/api/python + +### Python ### +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +*.egg-info/ +.installed.cfg +*.egg + +# 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/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py + +# Flask instance folder +instance/ + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# IPython Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery beat schedule file +celerybeat-schedule + +# dotenv +.env + +# virtualenv +venv/ +ENV/ + +# Spyder project settings +.spyderproject + +# Rope project settings +.ropeproject + diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ac90f26..dad72b8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,7 +7,7 @@ - id: check-yaml - id: end-of-file-fixer - id: flake8 - exclude: __init__.py + exclude: __init__.py,docs/conf.py - id: name-tests-test - id: autopep8-wrapper - id: requirements-txt-fixer diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..fecfd2f --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,230 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) + $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pyentrypoint.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pyentrypoint.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/pyentrypoint" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pyentrypoint" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..9b38e50 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,293 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# pyentrypoint documentation build configuration file, created by +# sphinx-quickstart on Thu Apr 28 23:51:03 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. +import os +import sys + +sys.path.insert(0, os.path.abspath('..')) + +from setup import __version__ + +# 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. +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# 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.ext.doctest', + 'sphinx.ext.coverage', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'pyentrypoint' +copyright = '2016, Christophe Mehay' +author = 'Christophe Mehay' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = __version__ +# The full version, including alpha/beta/rc tags. +release = __version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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 = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# html_title = 'pyentrypoint v0.3.0' + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or +# 32x32 pixels large. +# html_favicon = None + +# 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 any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'pyentrypointdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # 'preamble': '', + + # Latex figure (float) alignment + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'pyentrypoint.tex', 'pyentrypoint Documentation', + 'Christophe Mehay', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pyentrypoint', 'pyentrypoint Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'pyentrypoint', 'pyentrypoint Documentation', + author, 'pyentrypoint', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False diff --git a/docs/config.rst b/docs/config.rst new file mode 100644 index 0000000..83878d6 --- /dev/null +++ b/docs/config.rst @@ -0,0 +1,221 @@ +pyentrypoint-config.yml +======================= + +This is an example of ``entrypoint-config.yml`` file. + +.. code:: yaml + + # Entrypoint configuration example + + # This entry should reflect CMD in Dockerfile + command: git + + # This is a list with some subcommands to handle + # when CMD is not `git` here. + # By default, all args started with hyphen are handled. + subcommands: + - "-*" + - clone + - init + - ls-files + # etc... + + # User and group to run the cmd. + # Can be name or uid/gid. + # Affect only command handled. + # Dockerfile USER value by default. + user: 1000 + group: 1000 + + # These files should exist (ADD or COPY) + # and should be jinja templated. + # Note: if config files end with ".tpl", the extension will be removed. + config_files: + - /etc/gitconfig + - .ssh/config.tpl # Will apply to ".ssh/config" + - /tmp/id_rsa: .ssh/id_rsa # Will apply "/tmp/id_rsa" template to ".ssh/id_rsa" + + + # These environment variables will be wiped before + # exec command to keep them secret + # CAUTION: if the container is linked to another one, + # theses variables will passed to it anyway + secret_env: + - SSHKEY + + # Links are handled here + # Port, name, protocol or env variable can be used to identify the links + # Raise an error if the link could not be identified + links: + 'ssh': + port: 22 + name: 'ssh*' + protocol: tcp + # env can be list, dictionary or string + env: + FOO: bar + # Single doesn't allow multiple links for this ID + # false by default + single: true + # Set to false to get optional link + # true by default + required: true + + # Commands to run before applying configuration + pre_conf_commands: + - echo something > to_this_file + + # commands to run after applying configuration + post_conf_commands: + - echo "something else" > to_this_another_file + + # Cleanup environment from variables created by linked containers + # before running command (True by default) + clean_env: True + + # Enable debug to debug + debug: true + +yaml references +~~~~~~~~~~~~~~~ + +command +^^^^^^^ + +``command`` should reflect CMD in Dockerfile. + +If the container is not started with this commande, +the configuration will not be applied. + +subcommands +^^^^^^^^^^^ + +``subcommands`` is a list with some subcommands to handle. + +Running container with a matching subcommand run it with setuped ``command``. + +.. code:: yaml + + subcommands: + - "-*" + - clone + - init + - ls-files + +.. pull-quote:: + + **Note**: Globbing pattern is enabled here. + + By default, all args started with hyphen are handled. + +user, group +^^^^^^^^^^^ + +User and group to run the ``command``. +Can be name or uid/gid. +Affect only command handled. + +.. code:: yaml + + user: 1000 + group: root + +.. pull-quote:: + + **Note**: Dockerfile USER value by default. + +config_files +^^^^^^^^^^^^ + +These files should exist (ADD or COPY) and should be jinja templated. + +.. code:: yaml + + config_files: + - /etc/gitconfig + - .ssh/config.tpl # Will apply to ".ssh/config" + - /tmp/id_rsa: .ssh/id_rsa # Will apply "/tmp/id_rsa" template to ".ssh/id_rsa" + +.. pull-quote:: + **Note**: if config files end with ".tpl", the extension will be removed. + +secret_env +^^^^^^^^^^ + +These environment variables will be wiped before +running command to keep them secret. + +.. code:: yaml + + secret_env: + - SSHKEY + - APIKEY + +.. pull-quote:: + + **CAUTION**: if the container is linked to another one, + theses variables will be sent to it anyway. + + +links +^^^^^ + +Links are handled here. + +Port, name, protocol or environment variables can be used to identify the links. + +.. code:: yaml + + links: + 'ssh': # This is the name to handle link in templates + port: 22 + name: 'ssh*' + protocol: tcp + # env can be list, dictionary or string + env: + FOO: bar + # Single doesn't allow multiple links for this ID + # false by default + single: true + # Set to false to get optional link + # true by default + required: true + +.. pull-quote:: + + **Note**: All parameters are optionals. + + Raise an error if the link could not be identified. + + +pre_conf_commands +^^^^^^^^^^^^^^^^^ + +List of shell commands to run before applying configuration + +.. code:: yaml + + pre_conf_commands: + - echo something > to_this_file + + +post_conf_commands +^^^^^^^^^^^^^^^^^^ + +List of shell commands to run after applying configuration + +.. code:: yaml + + post_conf_commands: + - echo "something else" > to_this_another_file + +clean_env +^^^^^^^^^ + +Cleanup environment from variables created by linked containers +before running command (True by default) + +debug +^^^^^ + +Print some debug. diff --git a/docs/extra.rst b/docs/extra.rst new file mode 100644 index 0000000..f044eca --- /dev/null +++ b/docs/extra.rst @@ -0,0 +1,7 @@ +Options setup +============= + +Some setups can be overridden using environment variables in the container. + +- ``ENTRYPOINT_CONFIG`` overrides path of ``entrypoint-config.yml`` + file. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..45b91d1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,44 @@ +.. pyentrypoint documentation master file, created by + sphinx-quickstart on Thu Apr 28 23:51:03 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to pyentrypoint's documentation! +======================================== + +**pyentrypoint** is a tool written in ``Python`` to manage Docker +containers ``ENTRYPOINT``. + +This tool avoids writing shell scripts to: + +- Handle commands and sub commands +- Identify linked containers +- Auto configure container using `jinja2` templates +- Run commands before starting service +- Clean environment before running service +- Increase security by setuid/setgid service + +Contents: + +.. toctree:: + :maxdepth: 3 + + installation + config + templates + extra + + +Working examples +~~~~~~~~~~~~~~~~ + +- `Tor hidden + service `__ + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..1868199 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,34 @@ +Installation +============ + +All you need to do is to setup a ``yaml`` file called +``entrypoint-config.yml`` and to install **pyentrypoint** in your +``Dockerfile`` using pip. + +.. code:: dockerfile + + FROM debian + # Installing git for example + RUN apt-get update && apt-get install git python-pip -y + # Install pyentrypoint + RUN pip install pyentrypoint + # Copy config file in the current WORKDIR + COPY entrypoint-config.yml . + # Set ENTRYPOINT + ENTRYPOINT ['pyentrypoint'] + # git will be the default command + CMD ['git'] + +.. code:: dockerfile + + FROM alpine + # Installing git for example + RUN apk add --update py-pip git + # Install pyentrypoint + RUN pip install pyentrypoint + # Copy config file in the current WORKDIR + COPY entrypoint-config.yml . + # Set ENTRYPOINT + ENTRYPOINT ['pyentrypoint'] + # git will be the default command + CMD ['git'] diff --git a/docs/templates.rst b/docs/templates.rst new file mode 100644 index 0000000..0e2281c --- /dev/null +++ b/docs/templates.rst @@ -0,0 +1,94 @@ +Templates +========= + +You can generate configuration for your service with jinga2 template. + +Here is an example for an hypothetical ssh config file: + +.. code:: jinja + + host server: + hostname {{links.ssh.ip}} + port {{links.ssh.port}} + +Templates will be replaced with ip address and port of the identified +link. All links can be accessed from ``links.all``, this is a tuple of +links you can iterate on it. + +.. code:: jinja + + {% for link in links.all %} + host {{link.names[0]}} + hostname {{link.ip}} + port {{links.port}} + {% endfor %} + +If you change the option ``single`` to ``false`` in the +``entrypoint-config.yml``, the identified link ``ssh`` will become a +tuple of links. You must iterate on it in the ``jinja`` template. + +.. code:: jinja + + {% for link in links.ssh %} + host {{link.names[0]}} + hostname {{link.ip}} + port {{links.port}} + {% endfor %} + +Accessing environment in template. + +.. code:: jinja + + {% if 'SSHKEY in env' %} + {{env['SSHKEY']}} + {% endfor %} + +Accessible objects +~~~~~~~~~~~~~~~~~~ + +You have 4 available objects in your templates. + +- ``config`` +- ``links`` +- ``containers`` +- ``environ`` + +config +^^^^^^ + +``Config`` reflect the config file. You can retrieve any setup in this +object. + +(see ``config.py``) + +links +^^^^^ + +``Links`` handles ``Link`` objects. You can identify links using +wildcard patterns in the configuration file. + +``link`` is related to one physical link (one ip and one port). + +``link`` handles the following attributes: - ``ip`` - link ip - ``port`` +- link port (integer) - ``environ`` - related container environment - +``protocol`` - link protocol (``tcp`` or ``udp``) - ``uri`` - link URI +(example: ``tcp://10.0.0.3:80``) - ``names`` - tuple of related +container names + +containers +^^^^^^^^^^ + +``containers`` handles a tuple of ``container`` object. + +``container`` handles the following attributes: - ``ip`` - container ip +- ``environ`` - container environment - ``names`` - List of containers +names - Names are sorted by length, but container ID will be the last +element. - ``id`` - Hexadecimal container ID (if available, empty string +else) - ``links`` - Tuple of ``link`` objects related to this container + +environ +^^^^^^^ + +``environ`` is the environment of the container (os.environ). + +``env`` is an alias to ``environ``. diff --git a/setup.py b/setup.py index 7f3fd5f..74be21e 100644 --- a/setup.py +++ b/setup.py @@ -5,52 +5,55 @@ from setuptools import setup # Thanks Sam and Max -setup( +__version__ = '0.3.1' - name='pyentrypoint', +if __name__ == '__main__': + setup( - version='0.3.0', + name='pyentrypoint', - packages=find_packages(), + version=__version__, - author="Christophe Mehay", + packages=find_packages(), - author_email="cmehay@nospam.student.42.fr", + author="Christophe Mehay", - description="pyentrypoint manages entrypoints in Docker containers.", + author_email="cmehay@nospam.student.42.fr", - long_description=open('README.md').read(), + description="pyentrypoint manages entrypoints in Docker containers.", - install_requires=['Jinja2>=2.8', - 'PyYAML>=3.11', - 'colorlog>=2.6.1', - 'argparse>=1.4.0', - 'six>=1.10.0'], + long_description=open('README.md').read(), - include_package_data=True, + install_requires=['Jinja2>=2.8', + 'PyYAML>=3.11', + 'colorlog>=2.6.1', + 'argparse>=1.4.0', + 'six>=1.10.0'], - url='http://github.com/cmehay/pyentrypoint', + include_package_data=True, - classifiers=[ - "Programming Language :: Python", - "Development Status :: 1 - Planning", - "License :: OSI Approved :: BSD License", - "Natural Language :: English", - "Operating System :: POSIX :: Linux", - "Programming Language :: Python :: 2", - "Programming Language :: Python :: 3", - "Programming Language :: Python :: 2.7", - "Programming Language :: Python :: 3.5", - "Topic :: System :: Installation/Setup", - ], + url='http://github.com/cmehay/pyentrypoint', - - entry_points={ - 'console_scripts': [ - 'pyentrypoint = pyentrypoint.__main__:main', + classifiers=[ + "Programming Language :: Python", + "Development Status :: 1 - Planning", + "License :: OSI Approved :: BSD License", + "Natural Language :: English", + "Operating System :: POSIX :: Linux", + "Programming Language :: Python :: 2", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 2.7", + "Programming Language :: Python :: 3.5", + "Topic :: System :: Installation/Setup", ], - }, - license="WTFPL", -) + entry_points={ + 'console_scripts': [ + 'pyentrypoint = pyentrypoint.__main__:main', + ], + }, + + license="WTFPL", + + )