You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2014/12/17 18:24:11 UTC
[37/50] [abbrv] incubator-brooklyn git commit: update the docs on the
docs themselves
update the docs on the docs themselves
add info on the docs plugins/code to docs README,
and update/simplify the documentation re docs in the website and guide;
more desired on this latter but the minimum has been done here I think
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/ddcd1cfe
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/ddcd1cfe
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/ddcd1cfe
Branch: refs/heads/master
Commit: ddcd1cfeb956c162427937e7e456a6b8d5a05b6d
Parents: c3bf721
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Wed Dec 17 09:27:26 2014 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Wed Dec 17 09:27:26 2014 +0000
----------------------------------------------------------------------
docs/README.md | 45 ++++++++++++-
docs/guide/dev/tips/update-docs.md | 66 ++------------------
.../website/community/how-to-contribute-docs.md | 34 +++++++---
3 files changed, 75 insertions(+), 70 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ddcd1cfe/docs/README.md
----------------------------------------------------------------------
diff --git a/docs/README.md b/docs/README.md
index b090785..f5a2d73 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -198,7 +198,7 @@ copied to `${BROOKLYN_SITE_DIR-../../incubator-brooklyn-site-public}`:
# latest guide, relative to /v/latest/
_build/build.sh guide-latest --install
- # latest guide, relative to /v/<version>/
+ # versioned guide, relative to /v/<version>/
_build/build.sh guide-version --install
Next it is recommended to go to the SVN dir and
@@ -211,3 +211,46 @@ You must then check in the changes:
svn ci -m 'Update Brooklyn website'
The changes should become live within a few minutes.
+
+
+More Notes on the Code
+----------------------
+
+# Plugins
+
+We use some custom Jekyll plugins, in the `_plugins` dir:
+
+* include markdown files inside other files (see, for example, the `*.include.md` files
+ which contain text which is used in multiple other files)
+* parse JSON which we can loop over in our markdown docs (to do the TOC in the `guide`)
+* generate the site structure (for the `website`)
+* trim whitespace of ends of variables
+
+
+# Guide ToC
+
+In the `guide`, JSON table-of-contents files (toc.json) are our lightweight solution to the
+problem of making the site structure navigable (the menus at left).
+If you add a page, simply add the file and a title to the `toc.json` in that directory
+and it will get included in the menu.
+
+You can also configure a special toc to show on your page, if you wish, by setting the toc variable in the header.
+Most pages declare the `guide-normal` layout (in `_layouts/`) which builds a menu in the left side-bar
+(`_includes/sidebar.html`) using the JSON, automatically detecting which page is active.
+
+
+# Website ToC
+
+The `website` follows a different, simpler pattern, using the `site-structure` plugin
+and front-matter in each page. When adding a page, simply add the relevant front matter
+in the page(s) which refer to them.
+
+
+# Versions
+
+Archived versions are kept under `/v/` in the website. New versions should be added with
+the appropriate directory (`guide-version` above will do this). These versions take their
+own copy of the `style` files so that changes there will not affect future versions.
+
+A list of available versions also needs to be updated. This is referenced from the `website`.
+<!-- TODO: where -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ddcd1cfe/docs/guide/dev/tips/update-docs.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/update-docs.md b/docs/guide/dev/tips/update-docs.md
index 0f2aafb..ccb573e 100644
--- a/docs/guide/dev/tips/update-docs.md
+++ b/docs/guide/dev/tips/update-docs.md
@@ -4,67 +4,11 @@ title: Updating the Docs
toc: /guide/toc.json
---
+<!-- TODO retire this page -->
+
The Brooklyn docs live in the **docs** project in the Brooklyn codebase.
It's built using standard jekyll/markdown with a few extensions.
-
-## Jekyll
-
-Firstly, install Pygments (used for source code highlighting):
-
- sudo easy_install Pygments
-
-Next, install Jekyll and the other Ruby Gems that we need:
-
- bundle install
-
-Then, in the `docs/` directory, run:
-
- ./_scripts/jekyll-debug.sh
-
-Visit [http://localhost:4000/](http://localhost:4000/) and you should see the documentation.
-
-
-## Extensions
-
-In addition to the standard pygments plugin for code-highlighting,
-we use some custom Jekyll plugins (in the `_plugins` dir) to:
-
-* include markdown files inside other files
- (see, for example, the `*.include.md` files which contain text
- which is used in multiple other files)
-* parse JSON which we can loop over in our markdown docs
-* trim whitespace of ends of variables
-
-Using JSON table-of-contents files (`toc.json`) is our lightweight solution
-to the problem of making the site structure navigable (the menus at left).
-If you add a page, simply add the file (with full path from project root)
-and a title to the toc.json in that directory, and it will get included
-in the menu. You can also configure a special toc to show on your page,
-if you wish, by setting the toc variable in the header.
-Most pages declare the "page" layout (`_layouts/page.html`) which builds
-a menu in the left side-bar (`_includes/sidebar.html`) using the JSON --
-and automatically detecting which page is active.
-
-
-## Publishing
-
-Because GitHub don't run plugins (they run with the `--safe` option),
-the site is built off-line and uploaded to github, where the documentation is hosted.
-
-This makes the process a little more tedious, but it does have the advantage
-that the documentation lives right in the Brooklyn project,
-easy to open alongside the code inside your IDE.
-
-The off-line build can be done using `/docs/_scripts/build.sh`,
-including both jekyll markdown documentation and Brooklyn javadoc,
-with the result of this copied to the `brooklyncentral/brooklyncentral.github.com`
-github project (as per the GitHub pages documentation).
-[brooklyn.io](http://brooklyn.io) is CNAMEd to [brooklyncentral.github.com](brooklyncentral.github.com)
-for convenience.
-
-The latest stable version typically lives in the root of the `brooklyncentral.github.com` project.
-Archived versions are kept under `/v/*` with logic in the markdown for
-[meta/versions]({{ site.path.guide }}/meta/versions.html) to link to related versions.
-Additional instructions and scripts for automating the installs can be found in `/docs/_scripts/`.
-
+Instructions for building and working with docs are in a `README.md` file
+in that folder; for the most recent version of instructions click
+[here](https://github.com/apache/incubator-brooklyn/tree/master/docs/README.md).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ddcd1cfe/docs/website/community/how-to-contribute-docs.md
----------------------------------------------------------------------
diff --git a/docs/website/community/how-to-contribute-docs.md b/docs/website/community/how-to-contribute-docs.md
index 5241c98..b6b3cd5 100644
--- a/docs/website/community/how-to-contribute-docs.md
+++ b/docs/website/community/how-to-contribute-docs.md
@@ -4,6 +4,11 @@ title: How to Contribute Documentation
navgroup: community
---
+<!-- TODO do we want this page? can be simplified a lot since the process is identical as for how-to-contribute,
+ with the exception of the "Edit this Page" (and reminder we can accept small changes without CLA or Jira);
+ we could promote much of the content from README.md to here... -->
+
+
Welcome and thank you for your interest in contributing to Apache Brooklyn! This guide will take you through the
process of making contributions to the Apache Brooklyn website and documentation.
@@ -11,16 +16,20 @@ process of making contributions to the Apache Brooklyn website and documentation
Two types of documentation
--------------------------
+The Brooklyn docs live in the **docs** project in the Brooklyn codebase,
+built using standard jekyll/markdown with a few extensions.
+
The Brooklyn documentation is split into two parts:
- **The main website and shared documentation**. This covers the root website
- and all pages that are not part of the version-specific user manual. This
- guide describes how to work with this documentation.
-- **Version-specific user manual**. These pages have a URL with a path that
- begins /v/*version-number* - for example,
- https://brooklyn.incubator.apache.org/v/0.7.0-M1. This documentation is part
- of the main source code, so please refer to the [How to contribute source
- code](how-to-contribute.html) for help with modifying these pages.
+ and all pages that are not part of the version-specific user guide.
+ Content for this is in the `website` directory.
+
+- **Version-specific user guide**. These pages have a URL with a path that
+ begins /v/*version-number*: for example,
+ https://brooklyn.incubator.apache.org/v/0.7.0-SNAPSHOT and <!-- BROOKLYN-VERSION -->
+ the special *latest* set at https://brooklyn.incubator.apache.org/v/latest .
+ Content for this is in the `guide` directory.
Contributor license agreement
@@ -82,7 +91,7 @@ Contributing using GitHub
-------------------------
Our GitHub repository is located at
-[https://github.com/apache/incubator-brooklyn-site](https://github.com/apache/incubator-brooklyn-site)
+[https://github.com/apache/incubator-brooklyn](https://github.com/apache/incubator-brooklyn)
Your commit messages must properly describes the changes that have been made and
their purpose ([here are some
@@ -106,6 +115,7 @@ again if master has moved before accepting your patch.
Finally, add a comment in the Jira issue with a link to the pull request so we
know the code is ready to be reviewed.
+
### Reviews
The Apache Brooklyn community will review your pull request before it is merged.
@@ -138,3 +148,11 @@ patches attached to a Jira issue. Our canonical repository is located at
When producing patches, please use `git format-patch` or a similar mechanism -
this will ensure that you are properly attributed as the author of the patch
when a committer merges it.
+
+
+For More Information
+--------------------
+
+Advanced instructions for building, previewing and publishing docs are in a `README.md` file
+in the `docs` folder; see those instructions
+[here](https://github.com/apache/incubator-brooklyn/tree/master/docs/README.md).