From c4c57ac605eca91357926e9b8d8615ade6c36bc9 2018-02-26 10:27:18 From: Branko Majic Date: 2018-02-26 10:27:18 Subject: [PATCH] GC-2: Adding initial documentation skeleton with some basic information about the project: - Added basic documentation describing the project. - Updated gitignore file to ensure documentation build artifacts stay out of the repository. - README file placed at top directory for convenient access. --- diff --git a/.gitignore b/.gitignore index 0ccd7f664198bbf0abb49424c30ea6d9c0458d65..91c9b8ad7077886389599f22085774bb2f2d86e6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ # Ignore IDE and backup files. *~ -.#* \ No newline at end of file +.#* + +# Ignore build artefacts. +docs/_build/ \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..e6308cd84e755e89bbfde9c9c3bb4187daf62d84 --- /dev/null +++ b/README.rst @@ -0,0 +1,86 @@ +.. Copyright (C) 2018 Branko Majic + + This file is part of Gimmecert documentation. + + This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 + Unported License. To view a copy of this license, visit + http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative + Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. + + +About Gimmecert +=============== + +Gimmecert is a simple CLI tool for quickly issuing X.509 server and +client certificates using locally-generated CA hierarchy with minimal +hassle. + +The tool is useful for issuing certificates in: + +- Local environment, when trying out a piece of new software that + depends on use of certificates. +- Development environment, when it is necessary to issue certificates + either for purpose of integration with other systems, or for ability + to develop new feature that involves use of certificates. +- Testing/CI/CD environment, when it is necessary to deploy/configure + tests to use certificates in order to ensure the tests are run + properly and in full. + +At time of this writing, Gimmecert is compatible with the following +Python versions: + +- *Python 3.4+* + + +Why was this tool created? +-------------------------- + +The tool was created to remove the pain of setting-up a CA hierarchy, +and then using this hierarchy to issue a couple of test certificates. + +While there are existing tools that can be used to this end (in +particular the OpenSSL's CLI and GnuTLS' ``certtool``), the process of +using them is tedious, slow, and error-prone. + +There are some more long-lived solutions out there, in form of +full-blown CAs, but those can be both an overkill and resource hog +when all a person needs is a couple of certificates that can be thrown +away. + + +Features +-------- + + +Support +------- + +In case of problems with the tool, please do not hesitate to contact +the author at **gimmecert (at) majic.rs**. Known issues and planned +features are tracked on website: + +* https://projects.majic.rs/gimmecert/ + +The library is hosted on author's own server, alongside a mirror on +Github: + +* https://code.majic.rs/gimmecert +* https://github.com/azaghal/gimmecert + + +License +------- + +Gimmecert *code* is licensed under the terms of GPLv3, or (at +your option) any later version. You should have received the full copy of the +GPLv3 license in the local file **LICENSE-GPLv3**, or you may read the full text +of the license at: + +* https://www.gnu.org/licenses/gpl-3.0.txt + +Gimmecert *documentation* is licensed under the terms of CC-BY-SA 3.0 +Unported license. You should have received the full copy of the CC-BY-SA 3.0 +Unported in the local file **LICENSE-CC-BY-SA-3.0-Unported**, or you may read +the full text of the license at: + +https://creativecommons.org/licenses/by-sa/3.0/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..9f2209a8d62511f16eb59433b32092f16d3899a5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,31 @@ +# +# Copyright (C) 2018 Branko Majic +# +# This file is part of Gimmecert documentation. +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 +# Unported License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative +# Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. +# + +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = Gimmecert +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) diff --git a/docs/_static/.keep b/docs/_static/.keep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/docs/_templates/.keep b/docs/_templates/.keep new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 0000000000000000000000000000000000000000..5cafdf2d54be13854f1fc50662c0dfd770fbfcf0 --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,10 @@ +.. Copyright (C) 2018 Branko Majic + + This file is part of Gimmecert documentation. + + This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 + Unported License. To view a copy of this license, visit + http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative + Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. + +.. include:: ../README.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..c3de7be3d704c570c084acf5c22f308a965da798 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,175 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2018 Branko Majic +# +# This file is part of Gimmecert documentation. +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 +# Unported License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative +# Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. +# + +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/stable/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 = 'Gimmecert' +copyright = '2018, Branko Majic' +author = 'Branko Majic' + +# The short X.Y version +version = '0.0-dev' +# The full version, including alpha/beta/rc tags +release = version + + +# -- 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.todo', +] + +# 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 master toctree document. +master_doc = 'index' + +# 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 + +# 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'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- 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 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Gimmecertdoc' + + +# -- 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, 'Gimmecert.tex', 'Gimmecert Documentation', + 'Branko Majic', 'manual'), +] + + +# -- 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, 'gimmecert', 'Gimmecert Documentation', + [author], 1) +] + + +# -- 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, 'Gimmecert', 'Gimmecert Documentation', + author, 'Gimmecert', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..e2e3b1c81545699ad8e917920d5fd4f3c8bc6349 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +.. Copyright (C) 2018 Branko Majic + + This file is part of Gimmecert documentation. + + This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 + Unported License. To view a copy of this license, visit + http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative + Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. + + +Gimmecert documentation +======================= + +Gimmecert is a simple CLI tool for quickly issuing X.509 server and +client certificates using locally-generated CA hierarchy with minimal +hassle. + + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + about + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000000000000000000000000000000000..694e3859ffc0b2aaa3ab5598d41ce106cb101f29 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,48 @@ +REM +REM Copyright (C) 2018 Branko Majic +REM +REM This file is part of Gimmecert documentation. +REM +REM This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 +REM Unported License. To view a copy of this license, visit +REM http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative +REM Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. +REM + + +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=Gimmecert + +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% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd