Calling web-design folks! Your chance to get involved with documentation.

Archives Ansible Project
1

For a while our documentation site was integrated with what we had up on Wordpress (yes, I know, ick), which resulted in local documentation builds not being styled well – which made it hard for people to work on documentation styling.

As a result, our docs site – while having a lot of great content up there – has lagged a bit in style and so forth.

We’re going to be fixing this, and eventually moving docs to a seperate server – docs.ansibleworks.com, which currently doesn’t quite exist. To do this first, one of the first steps is to get a good Sphinx theme (what we use to build the docs) going.

As a result, I have made some changes to the documentation source such that they appear styled when you build them locally (yay!), and this is, I thought, a great opportunity to get people who are interested in docs navigation and such to get involved.

I know we have a lot of greatly talented web developers out there.

What I have uploaded now is somewhat rough, it uses the “Solar” Sphinx theme instead of our customized one – Solar’s fine, but I think we can do a little better, in particular, we have some navigation challenges and such that might warrant doing a bit more.

Should folks have preferences in how navigation would work, perhaps you would like to submit pull requests and show your web design chops?

If you’d like to take a look, checkout Ansible

install “python-sphinx” to be able to build documentation
and do “make webdocs” from the checkout

the site will appear in docsite/htmlout

The documentation source lives in docsite/rst and the theme we are currently using lives in docsite/_themes/solar/*

A few things we could use some help with:

  • Finding a way for the modules to appear such that you select a category and then get a list of modules, and only see one at a time, rather than the sprawl we see now

  • Having some nicer styling for tables and code blocks, ideally with syntax highlighting where appropriate

  • Anything else you might think of

The only requirements we have:

  • Any scripts to build the docs must be self-contained in source control. (Previously someone came up with a great angular example but only they could build it! This was disappointing).

  • Let’s not create any mirrors of the docs, the idea is to have one place to contribute to them and not end up with stale forks.

  • Anything we do needs to be friendly to web spiders and site search

In any event, if folks would like to get involved, I’d love to have your stylistic input and contributions!

Thanks!

https://github.com/ansible/ansible/tree/devel/docsite

2

Just out of curiousity (I’m not a web designer :)), did you consider using readthedocs.org’s theme (https://github.com/snide/sphinx_rtd_theme) ?

3

I haven’t and that looks really good for the index, I’ll have to see what it docs to our templates.

(We might still need to do something custom-ish for the modules index at least?)

Seems a bit dependency heavy in the GitHub info but maybe not too bad.

4

Thanks for this – This looks QUITE excellent and I’m going to push changes to make this what we are using in the source control tree shortly.

It looks like we may need to restructure things in a few places to make sure everything starts with the right level of depth, and so that the modules are still easily skimmable.

It might be that we need to generate a different module index page for each category, but I’m hoping we can do something more clever.

5

Ok, I have everything in the tree looking pretty awesome if people want to try “make docs” and look around.

I could still use some help making module navigation good – right now it needs some work. This might mean splitting modules up into seperate category pages – and that’s easy – but I’d like other ideas or approaches if we can do something better.

To make it easy to tweak the theme I have a copy now in docsite/_themes

Thanks!!!

6

I like the new structure, however it seems that quite useful (at least, for me) introduction to playbooks from playbooks.rst is now gone. It was quite nicely covering in a tutorial format basic concepts:

  • playbook file format
  • various basics (hosts, users & tasks)
  • and others

Was it intentional or just happened by accident?

7

My current thoughts are this.

We tweak the module formatter code so it makes new pages like:

modules/modules_cloud.rst
modules/modules_networking.rst

etc

And in page that we auto-generate, it links to pages that are also auto-generated like:

modules/module_foo.rst

As a result, each module will appear on it’s own seperate page.

You will first go to the “Cloud” page to see all the cloud modules, and then click on the module you want from the list.

In the left hand index, when you click to expand modules, you’ll see all the categories below and can quickly hop to a per-category index.

If someone wishes to have at, please do, otherwise I may take a look at this starting around the 26th or 27th.

While we might not want to split all the modules into different pages just yet for easy browseability, I think we’ll still be able to show a full list (TOC tree) on the “modules” page that will satisify most folks.

This should mean we can have the new docs theme pushed before the first of the year.

So far I think this is a big improvement, we just need to make it work for the modules list, which is obviously the docs that people come back to the most.

8

Also, while I am hitting this part, I definitely COULD use some help with CSS around the module pages. It doesn’t look as good as it should.

You should be able to check this out now by doing “make webdocs” from the checkout and looking at some of the parameter examples.

Currently the generator code outputs raw HTML so I suspect it would be the case that we need to change the HTML to assign some CSS classes.

9

Not intentional. I think I overwrote a file.

Fixing now.

10

Playbooks intro omission now fixed!

11

Quick update:

I’m currently refactoring the module formatter script so I can more easily tweak it, I’d probably suggest folks not attempt sending patches to it until that’s done as it’s going to move around a lot.

12

Things are now modified so that each module category has it’s own index and each module renders on it’s own page.

I think this is a big improvement.

I had to do some massive refactoring on module_formatter.py to make sense of some things, so if you were using any unsupported features like JSON module format data, those don’t work anymore. Additionally, if you were using the manpages for pulling up info on a module, just use “ansible-doc modulename” instead.

The only thing really missing now that I can tell is the formatting on the individual module pages still needs work, because previously it was generated as an HTML table.

This file is here -

https://github.com/ansible/ansible/blob/devel/hacking/templates/rst.j2

This may be the case that some CSS classes just need to be applied. Help would be appreciated.

Let me know what you think about the module index and such.

I also ned to get some logos and things on the docs home page – it looks a little dull, but that will come!