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 -- Michael DeHaan <[email protected]> CTO, AnsibleWorks, Inc. http://www.ansibleworks.com/ -- You received this message because you are subscribed to the Google Groups "Ansible Project" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. For more options, visit https://groups.google.com/groups/opt_out.
