diff --git a/docs/.gitignore b/docs/.gitignore index 256be174..a0fa12cb 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ mgmt-documentation.pdf +_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..b419d666 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = mgmt +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) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..737bd03a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,158 @@ +# -*- coding: utf-8 -*- +# +# mgmt documentation build configuration file, created by +# sphinx-quickstart on Wed Feb 15 21:34:09 2017. +# +# 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. + +# 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('.')) + +from recommonmark.parser import CommonMarkParser + +# -- 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 = [] + +# 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_parsers = { + '.md': CommonMarkParser, +} + +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'mgmt' +copyright = u'2017, James Shubin' +author = u'James Shubin' + +# 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 = u'' +# The full version, including alpha/beta/rc tags. +release = u'' + +# 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 patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# 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 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'mgmtdoc' + + +# -- 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, 'mgmt.tex', u'mgmt Documentation', + u'James Shubin', '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, 'mgmt', u'mgmt 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, 'mgmt', u'mgmt Documentation', + author, 'mgmt', 'A next generation config management prototype!', + 'Miscellaneous'), +] diff --git a/docs/documentation.md b/docs/documentation.md index 27472b17..480b5846 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -1,51 +1,9 @@ # mgmt - - -## mgmt by [James](https://ttboj.wordpress.com/) -#### Available from: -#### [https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/) - -#### This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md) format. - -#### Table of Contents - -1. [Overview](#overview) -2. [Project description - What the project does](#project-description) -3. [Setup - Getting started with mgmt](#setup) -4. [Features - All things mgmt can do](#features) - * [Autoedges - Automatic resource relationships](#autoedges) - * [Autogrouping - Automatic resource grouping](#autogrouping) - * [Automatic clustering - Automatic cluster management](#automatic-clustering) - * [Remote mode - Remote "agent-less" execution](#remote-agent-less-mode) - * [Puppet support - write manifest code for mgmt](#puppet-support) -5. [Resources - All built-in primitives](#resources) -6. [Usage/FAQ - Notes on usage and frequently asked questions](#usage-and-frequently-asked-questions) -7. [Reference - Detailed reference](#reference) - * [Meta parameters](#meta-parameters) - * [Graph definition file](#graph-definition-file) - * [Command line](#command-line) - * [Compilation options](#compilation-options) -8. [Examples - Example configurations](#examples) -9. [Development - Background on module development and reporting bugs](#development) -10. [Authors - Authors and contact information](#authors) +This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md) format. ## Overview diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..778a8059 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +.. mgmt documentation master file, created by + sphinx-quickstart on Wed Feb 15 21:34:09 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to mgmt's documentation! +================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + documentation + quick-start-guide + resource-guide + prometheus + puppet-guide diff --git a/docs/prometheus.md b/docs/prometheus.md index d1a83419..facf24a0 100644 --- a/docs/prometheus.md +++ b/docs/prometheus.md @@ -1,25 +1,5 @@ -# mgmt +# Prometheus support - - -## Prometheus support Mgmt comes with a built-in prometheus support. It is disabled by default, and can be enabled with the `--prometheus` command line switch. diff --git a/docs/puppet-guide.md b/docs/puppet-guide.md index b70cfd89..9c4c4915 100644 --- a/docs/puppet-guide.md +++ b/docs/puppet-guide.md @@ -1,40 +1,4 @@ -# mgmt - - - -## mgmt Puppet guide -#### Available from: -#### [https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/) - -#### This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/docs/puppet-guide.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/puppet-guide.md) format. - -#### Table of Contents - -1. [Prerequisites](#prerequisites) - * [Testing the Puppet side](#testing-the-puppet-side) -2. [Writing a suitable manifest](#writing-a-suitable-manifest) - * [Unsupported attributes](#unsupported-attributes) - * [Unsupported resources](#unsupported-resources) - * [Avoiding common warnings](#avoiding-common-warnings) -3. [Configuring Puppet](#configuring-puppet) -4. [Caveats](#caveats) +# Puppet guide `mgmt` can use Puppet as its source for the configuration graph. This document goes into detail on how this works, and lists diff --git a/docs/quick-start-guide.md b/docs/quick-start-guide.md index 63961935..1039889e 100644 --- a/docs/quick-start-guide.md +++ b/docs/quick-start-guide.md @@ -1,41 +1,6 @@ -# mgmt +# Quick start guide - - -## mgmt quick start guide -#### Available from: -#### [https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/) - -#### This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/docs/quick-start-guide.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/quick-start-guide.md) format. - -#### Table of Contents - -0. [Introduction](#introduction) -1. [Vagrant](#vagrant) -2. [Dependencies](#dependencies) -3. [Quick start](#quick-start) -4. [Examples](#examples) -5. [Installation](#installation) -6. [Authors - Authors and contact information](#authors) - -## Introduction: +## Introduction This guide is intended for developers. Once `mgmt` is minimally viable, we'll publish a quick start guide for users too. In the meantime, please contribute! If you're brand new to `mgmt`, it's probably a good idea to start by reading the @@ -43,14 +8,14 @@ If you're brand new to `mgmt`, it's probably a good idea to start by reading the or to watch an [introductory video](https://github.com/purpleidea/mgmt/#on-the-web). Once you're familiar with the general idea, please start hacking... -## Vagrant: +## Vagrant If you would like to avoid doing the following steps manually, we have prepared a [Vagrant](https://www.vagrantup.com/) environment for your convenience. From the project directory, run a `vagrant up`, and then a `vagrant status`. From there, you can `vagrant ssh` into the `mgmt` machine. The MOTD will explain the rest. -## Dependencies: +## Dependencies Software projects have a few different kinds of dependencies. There are _build_ dependencies, _runtime_ dependencies, and additionally, a few extra dependencies required for running the _test_ suite. @@ -94,7 +59,7 @@ For building a visual representation of the graph, `graphviz` is required. ### Testing * golint `github.com/golang/lint/golint` -## Quick start: +## Quick start * Make sure you have golang version 1.6 or greater installed. * If you do not have a GOPATH yet, create one and export it: ``` @@ -116,24 +81,13 @@ cd $GOPATH/src/github.com/purpleidea/mgmt * To run continuously in the default mode of operation, omit the `--converged-timeout` option. * Have fun hacking on our future technology! -## Examples: +## Examples Please look in the [examples/](../examples/) folder for some examples! -## Installation: +## Installation Installation of `mgmt` from distribution packages currently needs improvement. At the moment we have: * [COPR](https://copr.fedoraproject.org/coprs/purpleidea/mgmt/) * [Arch](https://aur.archlinux.org/packages/mgmt/) Please contribute more! We'd especially like to see a Debian package! - -## Authors -Copyright (C) 2013-2016+ James Shubin and the project contributors - -Please see the -[AUTHORS](https://github.com/purpleidea/mgmt/tree/master/AUTHORS) file -for more information. - -* [github](https://github.com/purpleidea/) -* [@purpleidea](https://twitter.com/#!/purpleidea) -* [https://ttboj.wordpress.com/](https://ttboj.wordpress.com/) diff --git a/docs/resource-guide.md b/docs/resource-guide.md index 091ebcdf..d961da62 100644 --- a/docs/resource-guide.md +++ b/docs/resource-guide.md @@ -1,54 +1,4 @@ -# mgmt - - - -## mgmt resource guide by [James](https://ttboj.wordpress.com/) -#### Available from: -#### [https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/) - -#### This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/docs/resource-guide.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/resource-guide.md) format. - -#### Table of Contents - -1. [Overview](#overview) -2. [Theory - Resource theory in mgmt](#theory) -3. [Resource API - Getting started with mgmt](#resource-api) - * [Default - Get an empty resource with defaults](#default) - * [Validate - Validate the values of a resource struct](#validate) - * [Init - Initialize the resource](#init) - * [Close - Cleanup the resource](#close) - * [CheckApply - Check and apply resource state](#checkapply) - * [Watch - Detect resource changes](#watch) - * [Compare - Compare resource with another](#compare) - * [UIDs - Returns the list of resource UID's](#uids) - * [AutoEdges - Returns the autoedge interface matcher](#autoedges) - * [CollectPattern - Currently a stub, API will change](#collectpattern) - * [(UnmarshalYAML) - Optional, sets the YAML defaults](#unmarshalyaml) -4. [Further considerations - More information about resource writing](#further-considerations) -5. [Automatic edges - Adding automatic resources dependencies](#automatic-edges) -6. [Automatic grouping - Grouping multiple resources into one](#automatic-grouping) -7. [Send/Recv - Communication between resources](#send-recv) -8. [Composite resources - Importing code from one resource into another](#composite-resources) -9. [FAQ - Frequently asked questions](#frequently-asked-questions) -10. [Suggestions - API change suggestions](#suggestions) -11. [Authors - Authors and contact information](#authors) +# Resource guide ## Overview @@ -618,15 +568,3 @@ Additional blog posts, videos and other material [is available!](https://github. If you have any ideas for API changes or other improvements to resource writing, please let us know! We're still pre 1.0 and pre 0.1 and happy to break API in order to get it right! - -## Authors - -Copyright (C) 2013-2016+ James Shubin and the project contributors - -Please see the -[AUTHORS](https://github.com/purpleidea/mgmt/tree/master/AUTHORS) file -for more information. - -* [github](https://github.com/purpleidea/) -* [@purpleidea](https://twitter.com/#!/purpleidea) -* [https://ttboj.wordpress.com/](https://ttboj.wordpress.com/)