Write the docs!
Here you'll find our plans for the OpenNews Code Convening at Write the Docs, May 17, 2015.
Cheers to making Largo's documentation great!
Largo is a responsive WordPress theme and framework built for news sites.
Our primary audience for the work we'll do this weekend is the group of developers using Largo as the base/parent theme for their news site. We want to pay special attention to the INN's members that are short on time, money and technical skill.
The team at INN is small. We act as the tech support department for around 100 member organizations. We want and need our documentation to act as a tool for teaching members how to work with us more effectively.
This weekend, we'll focus on documenting:
- How to use Largo to build a child theme
- We'll be writing documentation for our sample child theme
- How we do development for Largo and child themes
- We have a set of tools for getting up and running using Vagrant, with the goal of making support and collaboration with members easier.
- Filling out the API docs/function reference, which means LOTS of cleanup of Largo source code.
- A lofty goal with 140+ open tickets, but a valuable resource for developers really digging in.
- Our audience has some background in programming. They are familiar with the high-level components of computer programming (e.g., variables, functions, conditions, etc.).
- Our audience may not be familiar with PHP, WordPress or Largo. We should use plain language and be as explicit as possible in order to help them reach their goal.
Resources for potential contributors:
Our docs are written using reStructuredText:
Our API docs/function reference are embedded in Largo's source code. This portion of the documentation uses an intermediate processing layer that extracts the documentation from the source code and creates reStructuredText files that Sphinx can understand and render.
- INN's doc for writing inline documentation
- This doc is aspirational and may not work 100% with the strategy we're using to document our source code. We're OK with that, for now.
- The current state of the docs
- "Write the Docs" milestone on Github
- Fork INN/Largo
Clone your branch:
git clone email@example.com:you/Largo.git
Check out the
git checkout write-the-docs
We use some Python libraries to generate our documentation. To install the requirements:
Not required, but it's recommended to use virtualenv:
mkvirtualenv largo-docs workon largo-docs
pip install -r requirements.txt
Our API docs/function reference uses doxphp to generate documentation based on the comments embedded in Largo's source code. You'll need to install doxphp to generate API docs.
Install with PEAR:
pear channel-discover pear.avalanche123.com pear install avalanche123/doxphp-beta
With all dependencies installed, running the generator is as simple as:
cd docs make php && make html
You can view the generated docs in the
- You can view the files with a browser as files
You can run a simple web server to view them.
cd docs/_build/html python -m SimpleHTTPServer 8081
Open a browser and point it at http://localhost:8081
The (ideal) procedure for contributing
- Choose an issue
- Comment on the issue that you're taking it.
Create a new branch with your contributions, named after the issue:
git checkout -b 613-partials-sticky-posts
Make your changes
Commit and push:
git commit git push -u origin 613-partials-sticky-posts
Create a pull request from your branch against INN/Largo, branch write-the-docs
- Done? Return to step 3.