This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository
https://gitbox.apache.org/repos/asf/incubator-datasketches-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new a6a36d6 Automatic Site Publish by Buildbot
a6a36d6 is described below
commit a6a36d6546332f0514e101b3932c03a6e17b2f14
Author: buildbot <[email protected]>
AuthorDate: Sat Jun 6 00:19:29 2020 +0000
Automatic Site Publish by Buildbot
---
output/README.md | 21 ++++++++++++++-------
1 file changed, 14 insertions(+), 7 deletions(-)
diff --git a/output/README.md b/output/README.md
index bda1444..13951ae 100644
--- a/output/README.md
+++ b/output/README.md
@@ -23,24 +23,31 @@ This is the DataSketches website source. Please visit the
main [DataSketches we
If you are interested in making contributions to this site please see our
[Community](https://datasketches.apache.org/docs/Community/) page for how to
contact us.
-### How the documentation website works
+### How the website works
+- The website is published directly from a specially named *asf-site* branch.
The content of this branch is generated automatically by *Jekyll* from the
*master* branch whenever changes are detected in the *master* branch. One
should never modify the content of the *asf-site* directly.
-The page content for the website is rendered directly from markdown documents.
These markdown documents are all referenced according to a table of contents
JSON document. The HTML for the website navigation is generated dynamically
from the JSON structure.
+- The *master* branch consists primarily of GitHub compatible *MarkDown*
documents, which hold all the written content.
+
+- There are two navigation mechanisms on the site to help the user find
documents: the *nav_bar* at the top of each page and the table-of-contents
*toc* drop-down menus on the left of each page. Individual pages can link to
each other using standard MarkDown links.
### How to contribute content to the website
In order to contribute changes to the website content, you will need to fork
this repository to your own GitHub profile.
-If you would like to change an existing page, changes can be made directly to
the relevant markdown document, and a pull request submitted. However, should
you intend to add a new page to the website, you will need to:
+If you only need to change an existing page, edit the relevant MarkDown page
locally and submit a pull-request to *master*.
+
+However, if you need to add a new page to the website, you may need to modify
the *toc* to enable users to find it:
+
+- Create the new MarkDown document with the appropriate layout definition, and
copyright notice. This can be copied from any of the existing pages. The types
of available layouts can be found in the */_layouts/* directory. Almost all
site documents use the *doc_page* layout. Place the new page in an appropriate
subdirectory in *master*.
-- Create a new markdown document with the appropriate layout definition, and
copyright notice. This can be copied from any of the existing pages.
+- The *toc* is generated statically by the developer/author, when it needs to
be updated, by running a small Java program called `TocGenerator.java` located
in */src/main/java/org/datasketches/docgen/*. The TocGenerator takes input
from the */src/main/resources/docgen/toc.json* file and save the output html in
*/_includes/toc.html* in *master*. Please do not edit the *toc.html* file
directly.
-- Ensure that there is a new entry in the table of contents JSON document.
This file is named `toc.json`, and may be located in the `resources/docgen`
subdirectory.
+- The *toc.json* file is pretty easy to figure out. It is a tree structure of
two types of elements, *Dropdown* and *Doc*. Each element has 4 or 5
*key:valu*e pairs. Make sure you structure the JSON correctly with matching
braces and brackets, and with commas between tree elements.
- Run the table of contents generator. The `runTocGenerator` method is a
static member of `TocGenerator.java`. You can run this from your preferred IDE
or from the command line. You should see the genenerated HTML as output to the
console.
-- Once you have run the generator, ensure that your new entry is included in
the `toc.html` file under the `_includes`
- subdirectory.
+- Once you have run the generator, ensure that your new entry is included in
the `toc.html` file under the `_includes` subdirectory.
+- If you have Jekyll installed on your computer you can visually check the
*toc* for proper operation before submitting your PR.
- Lastly, submit your pull request for review!
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
