Setting up Largo to contribute documentation¶
If you just want to help us write documentation, you don’t have to go through the complete setup process.
Once you’ve completed this recipe, you’ll be able to:
- rebuild the documentation
- preview your edits in a browser
- rebuild the translation files.
- push your edits to GitHub and request that we incorporate them in Largo
Setting up¶
This presumes that you’re familiar with the command line, and are using OSX or another UNIX-like system. If you’re not familiar with the command line, check out our collection of command-line resources.
Fork INN/Largo into your own GitHub account.
Clone your branch:
git clone git@github.com:you/Largo.git
Check out the write-the-docs branch:
git checkout write-the-docs
Install the required dependencies
We use some Python libraries to generate our documentation. To install the requirements:
cd docs
Not required, but it’s recommended to install and use virtualenv:
mkvirtualenv largo-docs workon largo-docs
Then:
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
Install with git. This requires you to know where your
bin
directory is, and may requiresudo
.git clone https://github.com/avalanche123/doxphp.git cd doxphp/bin mv doxph* /path/to/bin/
With all dependencies installed, you can run the generator:
cd docs make php && make html
But if you don’t want to have to manually recreate the documentation every time you save a file, you can run
grunt watch
from the Largo directory. This command only rebuilds documentation, though, and doesn’t recompile the API docs. (For a full list ofgrunt
commands, see the Largo grunt docs.You can view the generated docs in the docs/_build/html directory:
There are two main ways of doing this. First, you can view the files with a browser as files. It won’t be the best experience.
The other, better option is to run a sinple web server in the directory that the HTML documentation was output to, and then view them normally as a website in your browser:
cd docs/_build/html python -m SimpleHTTPServer 8081
The (ideal) procedure for contributing documentation¶
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 to INN/Largo
- How to make a PR on GitHub
- If it’s a big PR, please make sure it’s well-documented. Thanks!