brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [37/50] [abbrv] incubator-brooklyn git commit: update the docs on the docs themselves
Date Wed, 17 Dec 2014 17:24:11 GMT
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 <alex.heneveld@cloudsoftcorp.com>
Authored: Wed Dec 17 09:27:26 2014 +0000
Committer: Alex Heneveld <alex.heneveld@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).


Mime
View raw message