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
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
- 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 to INN/Largo
- How to make a PR on GitHub
- If it's a big PR, please make sure it's well-documented. Thanks!