apache/datasketches-website

Website for DataSketches.

Apache^® DataSketches™ Website

This is the DataSketches website source. Please visit the main DataSketches website for more information.

If you are interested in making contributions to this site please see our Community page for how to contact us.

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 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 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.

• 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.

• 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:value 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.

• 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!

datasketches-website's Issues

Includes in GitBook

As a part of migration to GitBook we need to understand how to include modules there

Highlight Logic Fails

https://github.com/apache/incubator-datasketches-website/blob/c340ce0558319d4f6cf62e1aefadc7a66ad5b581/_includes/tocScript.html#L56

Try's to be smart and highlight the current nav element, but it seems to be failing to highlight, as well as opening the drop down menu which gets selected due to the href (#) of that menu item.

Update Copyright for year 2020

Fix in #77

broken links

There are broken links on the Theta sketch set operations page.
Specifically, the links in the "Testing" section point to a location in the java repo and raise a 404.

Publishing site using GitBook

As a part of migration to GitBook we need to understand how do we go from the source code to published ASF site

Collapsed menus

When I read the Theta documentation the links are heavily nested in the navigation tree. Navigating to the next page in the sequence involves re-opening the tree to locate the highlighted page, and clicking the next link.
This makes reading the documentation on mobile or a kindle quite difficult, especially for somebody with big fingertips!
Expanding the content menu was disabled in #83.
Is there a preferred alternate approach, such as navigation links that can be added to the bottom of each page?