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.

1. Fork INN/Largo into your own GitHub account.

2. Clone your branch:

    git clone [email protected]:you/Largo.git
   

3. Check out the write-the-docs branch:

    git checkout write-the-docs
   

4. 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
   

5. 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 require sudo.

       git clone https://github.com/avalanche123/doxphp.git
       cd doxphp/bin
       mv doxph* /path/to/bin/
     

6. 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 of grunt commands, see the Largo grunt docs.

7. 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

1. Choose an issue

2. Comment on the issue that you're taking it.

3. Create a new branch with your contributions, named after the issue:

    	git checkout -b 613-partials-sticky-posts
   

4. Make your changes

5. Commit and push:

    	git commit
    	git push -u origin 613-partials-sticky-posts
   

6. 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!