OF Documentation Site Specification

This is a design specification for the OpenFrameworks documentation website. Its goal is to make sure that the development of the site and the expectations of those writing the documentation are consistent, and to provide a structure for purpose.

@halfdanj and @bakercp are the current owners of this spec—any changes to this spec should be approved by both of them before being implemented. If you have suggestions or improvements to this spec, please communicate with them. If you would like help, @workergnome will facilitate communication.

High Level Goals

• There will be a publicly accessible website located at http://docs.openframeworks.cc.
• This website will contain documentation for every class, method, constant, variable, and enum (collectively * known as content items) that is intended for public-facing use in OpenFrameworks. This includes all addons included in the core distribution of OpenFrameworks.
• This website will NOT show documentation for content items that are only intended for use in the OpenFrameworks internals. This includes both private methods and internal-only content items.
• This website will contain versioned content for each release of OpenFrameworks, including the in-development master branch of the OF core.
• This site will be dynamically generated from the content and will dynamically update as content items change.

Content

• The content of the site will come from two locations:
  • The inline doxygen comments in the OpenFrameworks core
  • A collection of markdown files containing content describing content items, contained within a github repo which contains ONLY the markdown documentation content.
• Each content item will display both doxygen content and markdown content.
• The site will suppport having both, either one, or no content for a content item.
• The site will display function signatures, return values, and parameter documentation for each method.
• These will be extracted from the doxygen documentation and the clang interpreter.
• Doxygen for base classes will cascade up to classes which inherit from those base classes.
• The site will support at least the following doxygen tags:
  • \sa
  • \brief
  • \warning
  • \throws
  • \tparam
  • \param
  • \returns
  • \copydoc
  • \todo
  • \class
  • \p
  • \since
  • \section
  • \internal
  • \advanced (this is used to hide certain classes)
• Preferably, the site will support all standard doxygen tags.
• The doxygen content should strictly conform to doxygen standards, without OF-unique tags.
• \internal will be used for content items that should be hidden, because they are only used within the core.
• \advanced will be used to mark content items that are flagged in the documentation as provided for advanced developers.
• When both doxygen and markdown are provided, the doxygen should be shown first.
• The markdown should support inline codeblocks.
• The markdown should support images.
• Both doxygen and markdown will support linking to external webpages.
• Internal linking between content items will be supported in both Markdown and Doxygen.
• Content items will be grouped into a logical hierarchy.
  • This hierarchy will be specified in the content, not hardcoded into the site.
• Global functions in OF will be presented grouped in a logical structure
  • This structure will be determined within the OF code, not hardcoded into the site.
• There will be a table of contents for the site.
• When there are multiple signatures for a function, all signatures will be presented.
• All site content will be available for SEO purposes.

Navigation Standards

• There will be a unique URL for each content item.
• There will be a way to share a link that takes someone directly to the content for a given content item.
• There will be a way to search across the entire documentation for code.
• There will be a way to browse the entire codebase.
• It will be possible to link to each level of the logical hierarchy.

Development Standards

• The site will be developed with sufficient documentation as to allow maintenance by the OF community.
• The site will be developed to match the themes and styles of the ofWebsite.
• The source code provided on the github repo for the site will be sufficient to completely build the site.
• Any external dependencies must be publically available and installation instructions documented.
• The site will be designed such that the content can be regenerated by any developer.

Hosting and Deployment

• The site will be designed to be hosted and deployed on the OpenFrameworks Rackspace.
• The site will be designed to be able to be run locally on a developer's computer.
• The source code for the site will be hosted on Github within the OpenFrameworks team.
• The source code for the site will be released under the same license as OpenFrameworks.

Markdown File Specifications

• There will be a single markdown file for each function.
• These Markdown files are for high level descriptions and explanations, and they apply to all signatures of that function. There will not be per-signature markdown documents.
• The filename of the markdown files are the metadata that connects them to the the doxygen. There is no other metadata in the markdown.
• The filename structure will be className.functionName.md.
• The directory structure of the markdown within the github repo will be used to simplify finding relevant functions, but will not be used as metadata.

Nice to Haves

• The site's code could be reusable for addons that do not exist within the OF core.
• The complete source code of the documentation should be exportable as a static, searchable HTML site.