Contributing to the Documentation
The openFrameworks documentation is a community effort, and we'd love for people to contribute missing documentation, fix typos, add examples, and generally make it a better representation of the community. If you're interested in helping or if you're frustrated by something, there are two ways to contribute by modifying the documentation. The openFrameworks documentation is generated by the comments added to core files using doxygen, and by the markdown files. This guide focuses on the markdown files, and if you are getting started contribuiting to the documentation, you should start with them.
If you are interested in adding the documentation to the core files, scroll to the the end of this page.
To edit the markdown, there are two ways, the Easy Way, and the Hard Way.
First, a bit about the structure and formatting of the documentation.
Documentation Structure and Formatting
The documentation of the OF site is contained in a set of .markdown files on the openFrameworks ofSite Github. The documentation for each class is contained in a single .markdown file containing all the methods and variables of that class named after the class. They're contained in a directory structure that mirrors both the documentation website and the openFrameworks class structure.
For instance, if you're looking for the ofMesh documentation, it would be at:
_documentation/3d/ofMesh.markdown
For reasons lost to the mists of time, the functions of the class are in their own file:
_documentation/3d/ofMesh_functions.markdown
The documentation files are formatted in a modified version of the markdown syntax with the following structure:
# class ofClass
## Description
<description of the class goes here>
## Methods
methods of the class
_description: _
<Description & documentation goes here>
## Variables
variables of the class
_description: _
<Description & documentation goes here>
When editing, only add documentation in the spaces after ##Description or _description: _: All of the other lines are auto-generated and used in the build scripts that construct the site.
Links are added using normal markdown format:
[Link Title](http://google.com "alt text")
Images are added using normal markdown format:
The largest formatting exception from standard markdown is the code block syntax. Rather than using the standard indentation method, code blocks are marked with four tildes followed by curly braces with ".cpp" inside. A block is also ended with four tildes.
For example:
~~~~{.cpp}
// Get the area of that rectangle
float areaValue = myRect.getArea();
// areaValue will be 20000.0.
~~~~
Everything between the tildes will be formatted and highlighted as C++ code.
Things Not to Do:
DON'T add headers to your description, using the ### I'm A Header syntax: headers are used to separate individual functions during the build process, and you'll break the site.
DON'T add new functions or variables to the documents: they will be autogenerated every time openFrameworks releases a new version.
DON'T modify fields that are marked with field: value: they are flags used in building the site.
How to Modify the openFrameworks documentation:
Much like the openFrameworks project, the openFrameworks Website is on Github. Github is a website, and it's also a massive online code repository built around the distributed version control system git. Github is extremely open-source friendly and is a where an increasingly large amount of the world's open-source software is kept, modified, and updated.
Anybody can submit pull requests through Github to update the website. If you're interested in changing something but aren't really sure how git works, Github has made it really easy to modify text files directly from their website. All you need is a Github account, which is free for open-source projects, and for people working with open-source.
Getting an account is easy—just go to github.com and sign up!
Making Changes to the openFrameworks Documentation on Github
Step 1: Find the Class
Within the openFrameworks documentation, at the top of every class's page, there are two buttons on the top of the page for "Edit Class" and/or "Edit Functions":
If you click either of these buttons, you'll be taken to a page on github with a text area containing the entire documentation for that class or set of functions. It will look something like this:
Step 2: Edit the Documentation
Within that block of text, you'll find the method, variable, or function that you're interested in editing. Directly edit the text. When you've made your changes, you can propose the edit using the box below the text:
Write a summary and an optional brief description of the changes you made, and click the "Propose File Change" button.
Step 3: Review your Change
You'll end up on the following page, which will let you review your changes:
Below that will be a list of all of the lines of text that you've changed. It's a good practice to go through the changes and make sure that you didn't accidentally delete something and that your changes are what you thought they were. If you'd like to write a message to the person who will be reviewing your changes, you can do that, too.
When you're comfortable with your changes, press the "Send Pull Request" button. This will submit a pull request for review. It will end up in the list of pull requests on the site, to be approved by an administrator and pushed to the site. This usually happens pretty quickly, but this is a volunteer team, and sometimes it takes a couple days. Be patient—Github will send you an email when your change is merged into the site.
Congrats! You've just modified the openFrameworks documentation, contributed to the community, and made some future person's life better. Wasn't that easy?
Adding documentation to the core
The documentation in the core files uses Doxygen. Have a look at the doxygen website or at the other files in the core to get an idea about the syntax.
Usually, you should add the documentation to the markdown files. But there are case when you need to edit the files contained in the openFrameworks core files, for example when the signature of a method is different from what the documentation says, or the description is wrong or outdated.
When you do this, keep in mind that it is better to do not write too much documentation in the openFrameworks core, because otherwise the files become too long. Images and examples should be commited directly in the markdown files on the ofSite. Signature, parameters, short description and return values goes in the openFrameworks core repository, all the rest in the openFrameworks website repository.
Written by David Newbury with help from Bernardo Schorr and Chris Coleman.
The initial version was written at the openFrameworks/RaspberryPI workshop at the Frank-Ratchye STUDIO for Creative Inquiry, October 11-13, 2013.