Repository: mesos Updated Branches: refs/heads/master 3f54a5519 -> 6e210e5cc
Introduced General Documentation Guide and Markdown Documentation Style Guide. Review: https://reviews.apache.org/r/35510 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/6e210e5c Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/6e210e5c Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/6e210e5c Branch: refs/heads/master Commit: 6e210e5cc40c83885a4df617350b84418df741b3 Parents: 3f54a55 Author: Joerg Schad <[email protected]> Authored: Tue Jun 23 15:43:20 2015 +0200 Committer: Bernd Mathiske <[email protected]> Committed: Tue Jun 23 15:43:20 2015 +0200 ---------------------------------------------------------------------- docs/home.md | 6 +- docs/mesos-documentation-guide.md | 35 ++++++++++ docs/mesos-markdown-style-guide.md | 119 ++++++++++++++++++++++++++++++++ 3 files changed, 158 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/6e210e5c/docs/home.md ---------------------------------------------------------------------- diff --git a/docs/home.md b/docs/home.md index 0f848f1..d990cbe 100644 --- a/docs/home.md +++ b/docs/home.md @@ -50,8 +50,10 @@ layout: documentation * [Committing](/documentation/latest/committing/) guidelines for committing changes. * [Committers and Maintainers](/documentation/latest/committers/) a listing of project committers and component maintainers; useful when seeking feedback. * [Doxygen](/api/latest/c++/) documents the internal Mesos APIs. -* [C++ Style Guide](/documentation/latest/mesos-c++-style-guide/) -* [Doxygen Style Guide](/documentation/latest/mesos-doxygen-style-guide/) +* [Documentation Guide](/documentation/latest/mesos-documentation-guide/) + * [C++ Style Guide](/documentation/latest/mesos-c++-style-guide/) + * [Doxygen Style Guide](/documentation/latest/mesos-doxygen-style-guide/) + * [Markdown Style Guide](/documentation/latest/mesos-markdown-style-guide/) * [Development Roadmap](/documentation/latest/mesos-roadmap/) * [Release Guide](/documentation/latest/release-guide/) http://git-wip-us.apache.org/repos/asf/mesos/blob/6e210e5c/docs/mesos-documentation-guide.md ---------------------------------------------------------------------- diff --git a/docs/mesos-documentation-guide.md b/docs/mesos-documentation-guide.md new file mode 100644 index 0000000..42ed95f --- /dev/null +++ b/docs/mesos-documentation-guide.md @@ -0,0 +1,35 @@ +# Mesos Documentation Guide + +Documentation is an integral part of every good feature. It describes the intended usage and enables new users to start using and understanding the feature. + +We have three different kinds of documentation: + + +1. [MarkDown User Guides](/documentation/latest/mesos-markdown-style-guide/) + + User guides and non-code technical documentation are stored in markdown files in the `docs/` folder. These files get rendered for the [online documentation](http://mesos.apache.org/documentation/latest/). + + +2. [Doxygen API Documentation and Developer Guides as part of source code](/documentation/latest/mesos-doxygen-style-guide/) + + Doxygen API documentation needs only to be applied to source code parts that + constitute an interface for which we want to generate Mesos API documentation + files. Implementation code that does not participate in this should still be + enhanced by source code comments as appropriate, but these comments should not follow the doxygen style. + + Substantial libraries, components, and subcomponents of the Mesos system such as + stout, libprocess, master, slave, containerizer, allocator, and others + should have an overview page in markdown format that explains their + purpose, overall structure, and general use. This can even be a complete developer guide. + + +3. Regular source code documentation + + All other source code comments must follow the [Google Style Guide](https://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Comments). + + +## Conventions + +We follow the [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) +on how to use words such as "must", "should", "can", +and other requirement-related notions. http://git-wip-us.apache.org/repos/asf/mesos/blob/6e210e5c/docs/mesos-markdown-style-guide.md ---------------------------------------------------------------------- diff --git a/docs/mesos-markdown-style-guide.md b/docs/mesos-markdown-style-guide.md new file mode 100644 index 0000000..7ea0b1d --- /dev/null +++ b/docs/mesos-markdown-style-guide.md @@ -0,0 +1,119 @@ +# Mesos Markdown Style Guide + +This guide introduces a consistent documentation style to be used across the entire non-code documentation. +User guides and non-code technical documentation are stored in markdown files in the `docs/` folder. These files get rendered for the [online documentation](http://mesos.apache.org/documentation/latest/). + +**Note:** As of right now this is work in progress and the existing documentation might not yet comply to this style. + + +## What to document? + +Any new substantial feature should be documented in its own markdown file. +If the link between source code and documentation is not obvious, consider inserting a short code comment stating that there is non-code documentation that needs to be kept in sync and indicating where it is located. + + +## Keep documentation and style-guides in sync with code. + +When changing code consider whether you need to update the documentation. +This is especially relevant when introducing new or updating existing command line flags. +These should be reflected in `configuration.md`! + + +## Code Examples + +Code examples should be specified as follows: + +~~~{.txt} + ~~~{.cpp} + int main(int argc, char** argv) + { + .... + } + ~~~ +~~~ + + +## Notes/Emphasis + +Notes are used to highlight important parts of the text and should be specified as follows. + +~~~{.txt} +**Note:** Short note. +Continued longer note. +~~~ + +We use single backticks to highlight individual words in a sentence such as certain identifiers: + +~~~{.txt} +Use the default `HierarchicalDRF` allocator.... +~~~ + + +## Commands + +We use single backticks to highlight sample commands as follows: + +~~~{.txt} +`mesos-master --help` +~~~ + + +## Files/Path + +Files and path references should be specified as follows: + +~~~{.text} +Remember you can also use the `file:///path/to/file` or `/path/to/file` +~~~ + + +## Tables + +In order to avoid problems with markdown formatting we should specify tables in html directly: + +~~~{.html} +<table class="table table-striped"> + <thead> + <tr> + <th width="30%"> + Flag + </th> + <th> + Explanation + </th> + </thead> + <tr> + <td> + --ip=VALUE + </td> + <td> + IP address to listen on + </td> + </tr> + <tr> + <td> + --[no-]help + </td> + <td> + Prints this help message (default: false) + + </td> + </tr> +</table> +~~~ + + +## Indendation and Whitespace + +We use no extra indentation in markdown files. +We have one new line after section headings and two blank lines +in between sections. + +~~~{.txt} +... end of previous section. + + +## New Section + +Beginning of new section .... +~~~
