You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by be...@apache.org on 2015/06/23 15:45:49 UTC
mesos git commit: Introduced General Documentation Guide and Markdown
Documentation Style Guide.
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 <jo...@mesosphere.io>
Authored: Tue Jun 23 15:43:20 2015 +0200
Committer: Bernd Mathiske <be...@mesosphere.io>
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 ....
+~~~