Re-organise meta and configs for all the services

zbal commented 10 years ago

Currently we have 1 folder per service called meta and a single file called variables.yml. It is not enough and we need to extend it to be extracting data for the documentation.

Several things to do:

for every service / every version:
- rename meta to docs,
- rename variables.yml to configuration.yml
- prepend all configuration.yml with # Service name\n\n Some text doc (adapt obviously the text)
- add a new file in docs for each task defined in the tasks folder, named the same (ex. tasks/start.yml --> create docs/start.yml)
update the scripts in scripts:
- deploy.sh and build.sh (deploy is more important) - and make sure you adapt all the new paths --> docs from meta, variables to configuration
- update yaml2json.py script to use the 2nd document of the yaml file u = yaml.safe_load_all(doc) ; u.next() ; variables = u.next() the 1st u.next drops the 1st doc.

Let me know when it's good

kuno commented 10 years ago

One thing I am still confused is that the yesterday the example you give me is actually a markdown file with yaml front matter, if sooner or later will be human readble.

But currently all the file in devops-ansible are pure yaml, they are intend to be machine readable, and not optimized for generating docs from them.

kuno commented 10 years ago

Now with the task yaml file, what the output documentation structure will looks like? For example

docs/apache/
   - configuration.html
   - disable.html
   - enable.html
   - main.html
   ...

Is this ok?

zbal commented 10 years ago

A few changes in the output:

/docs/
  - index.html
  apache/
    - index.html (replaces configuration.html)
    - /tasks
      - index.html
      - disable.html
      - enable.html
      - ...
  nginx/
    - etc.

The index.html files is a simple file with link to the respective tasks or services/index

You can skip the main.html it doesn't represent nothing.

zbal commented 10 years ago

As for the representation of the yaml; I am not very familiar with the html semantic. But the idea is the following:

yaml is a tree
each leaf need to be represented with their default, name, validator, description
each branch should structure the sub leaves

Maybe something like:

each branch is a - going deeper as the walk down the tree occurs? or a
each leave is a list ?

zbal commented 10 years ago

Structure of a package index.html:

<h1>pkg name</h1>
the markdown content

<h1>Configuration</h1>
<!-- 1st items in the tree -->
<ul>
  <li>item_key1: description (default: default_val)</li>
  <li>item_key2: description (default: default_val)</li>
  <li>item_key3: description (default: default_val)</li>
</ul>
<h2>sub_branch1</h2>
<!-- items defined in the subbranch 1 -->
<ul>
  <li>item_key1: description (default: default_val)</li>
  <li>item_key2: description (default: default_val)</li>
  <li>item_key3: description (default: default_val)</li>
</ul>
<h3>sub_sub_branch</h3>
<!-- items defined in the sub_sub_branch -->
<ul>
  <li>item_key1: description (default: default_val)</li>
  <li>item_key2: description (default: default_val)</li>
  <li>item_key3: description (default: default_val)</li>
</ul>
<h2>sub_branch2</h2>
<!-- items defined in the subbranch 2 -->
<ul>
  <li>item_key1: description (default: default_val)</li>
  <li>item_key2: description (default: default_val)</li>
  <li>item_key3: description (default: default_val)</li>
</ul>

Then we may wanna have around some of the items to ease on the styling.

kuno commented 10 years ago

@zbal

One thing, is that ok I put all the task docs yaml file (not html) in packages/**/*/docs in to a sub folder packages/**/*/docs/tasks?

zbal commented 10 years ago

No - better have the tool to build everything and put them in a build folder like we do with other build process.

I do not want the doc to be captured in git - make sure the ./build folder is in .gitignore.

The documentation has to be build on the fly there is not point in versioning the html files.

zbal commented 10 years ago

Sorry - yes - I'm fine with the ./docs and ./docs/tasks folder organisation

kuno commented 10 years ago

@zbal For example, this is the apache configration docs as docs/apache/index.html

<!DOCTYPE html>
<html>
<head>
<title>apache document</title>
</head>
<body>
<h1></h1>
<h1 id="apache">Apache</h1>
<p>  Some text doc</p>

<h1>Configuration</h1>

<h2>user</h2>
<ul>

<li>default: www-data</li>

<li>description: Apache running user.</li>

<li>type: string</li>

<li>required: false</li>

</ul>

<h2>group</h2>
<ul>

<li>default: www-data</li>

<li>description: Apache running group.</li>

<li>type: string</li>

<li>required: false</li>

</ul>

<h2>timeout</h2>
<ul>

<li>default: 300</li>

<li>description: The number of seconds before receives and sends time out.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>keepalive</h2>
<ul>

<li>default: true</li>

<li>description: Whether or not to allow persistent connections.</li>

<li>type: string</li>

<li>required: false</li>

<h2>enum</h2>
<ul>

<li>0: true</li>

<li>1: false</li>

<li>2: true</li>

<li>3: false</li>

</ul>

</ul>

<h2>maxkeepaliverequests</h2>
<ul>

<li>default: 100</li>

<li>description: The maximum number of requests to allow during a persistent connection.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>keepalivetimout</h2>
<ul>

<li>default: 5</li>

<li>description: Number of seconds to wait for the next request from the same client on the same connection.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>prefork</h2>
<ul>

<h2>startservers</h2>
<ul>

<li>default: 5</li>

<li>description: Number of server processes to start.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 1</li>

</ul>

<h2>minspareservers</h2>
<ul>

<li>default: 2</li>

<li>description: Minimum number of server processes which are kept spare.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxspareservers</h2>
<ul>

<li>default: 10</li>

<li>description: Maximum number of server processes which are kept spare.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxclients</h2>
<ul>

<li>default: 150</li>

<li>description: Maximum number of server processes allowed to start.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxrequestsperchild</h2>
<ul>

<li>default: 4000</li>

<li>description: Maximum number of requests a server process serves.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

</ul>

<h2>worker</h2>
<ul>

<h2>startservers</h2>
<ul>

<li>default: 5</li>

<li>description: Initial number of server processes to start.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 1</li>

</ul>

<h2>minsparethreads</h2>
<ul>

<li>default: 25</li>

<li>description: Minimum number of worker threads which are kept spare,</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxsparethreads</h2>
<ul>

<li>default: 75</li>

<li>description: Maximum number of worker threads which are kept spare.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>threadlimit</h2>
<ul>

<li>default: 64</li>

<li>description: ThreadsPerChild can be changed to this maximum value during a graceful restart. ThreadLimit can only be changed by stopping and starting Apache.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>threadsperchild</h2>
<ul>

<li>default: 25</li>

<li>description: Constant number of worker threads in each server process.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxclients</h2>
<ul>

<li>default: 150</li>

<li>description: Maximum number of simultaneous client connections</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxrequestsperchild</h2>
<ul>

<li>default: 0</li>

<li>description: Maximum number of requests a server process serves.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

</ul>

<h2>event</h2>
<ul>

<h2>startservers</h2>
<ul>

<li>default: 5</li>

<li>description: Initial number of server processes to start.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>minsparethreads</h2>
<ul>

<li>default: 25</li>

<li>description: Minimum number of worker threads which are kept spare,</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxsparethreads</h2>
<ul>

<li>default: 75</li>

<li>description: Maximum number of worker threads which are kept spare.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>threadlimit</h2>
<ul>

<li>default: 64</li>

<li>description: ThreadsPerChild can be changed to this maximum value during a graceful restart. ThreadLimit can only be changed by stopping and starting Apache.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>threadsperchild</h2>
<ul>

<li>default: 25</li>

<li>description: Constant number of worker threads in each server process.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxclients</h2>
<ul>

<li>default: 150</li>

<li>description: Maximum number of simultaneous client connections</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

<h2>maxrequestsperchild</h2>
<ul>

<li>default: 0</li>

<li>description: Maximum number of requests a server process serves.</li>

<li>type: integer</li>

<li>required: false</li>

<li>minimum: 0</li>

</ul>

</ul>

</body>
</html>

Wiredcraft / devops-ansible

Re-organise meta and configs for all the services #41