Skip to content

Latest commit

 

History

History
128 lines (86 loc) · 4.45 KB

README.adoc

File metadata and controls

128 lines (86 loc) · 4.45 KB
Raw

docs_obazl

dev:

Edit directly in docs/src

To test: changedir to docs/, then $ bundle exec jekyll serve

Site is at localhost:4000/docs_obazl/index

DOCUMENTATION, demos, and tools for rules_ocaml, tools_opam, and tools_obazl.

The documentation is written in the asciidoc markup language. It uses the jekyll-asciidoc plugin to integrate with Github pages.

Based on the Documentation Jekyll theme.

Asciidoc sources

Pages for the User Guides and the tools_opam Reference Manual are written directly in asciidoc. Pages for the rules_ocaml Reference Manual are generated by Stardoc (see below).

layouts and includes

Each .adoc source page contains a header like:

layout: page_tools_opam
sidebar: sidebar_tools_opam_ug

Layouts are in docs/_layouts. They use the liquid templating language.

Layout templates may include fragments using liquid syntax, e.g. {% include topnav.html %}. The fragments are in docs/_includes. They also use liquid templating.

sidebars

Sidebars are implemented using template fragments with prefix sidebar_, located in docs/_includes. The data for the sidebars is located in .yml files located in docs/_data/sidebars; the fragments include the data by starting with a line like:

{% assign sidebar = site.data.sidebars[page.sidebar].entries %} (1)

  1. page.sidebar resolves to the value of the sidebar variable in the .adoc source file header.

So the inclusion structure is illustrated by this example:

  • docs/src/tools_opam/ug/opam_configuration.adoc header contains:

---
layout: page_tools_opam
sidebar: sidebar_tools_opam_ug
...
---

1 The layout variable resolves to docs/_layout/page_tools_opam.html

2 The page_tools_opam.html template contains: {% include sidebar_tools_opam.html %}

3 sidebar_tools_opam.html is located in docs/_includes; it contains {% assign sidebar = site.data.sidebars[page.sidebar].entries %}

4 site.data.sidebars resolves to docs/_data/sidebars, and page.sidebar resolves to the value of the sidebar variable in the page header shown above, i.e. sidebar_tools_opam_ug, so the sidebar reference resolves to docs/_data/sidebars/sidebar_tools_opam_ug.yml

The fields in sidebar_tools_opam_ug.yml, in turn, are referenced by sidebar_tools_opam.html (item 3 above) using liquid syntax; for example:

  <li class="sidebarTitle"><a href="{{sidebar[0].url}}">Reference: {{sidebar[0].product}}</a></li>

Here url and product are entry fields in sidebar_tools_opam_ug.yml.

Stardoc

Reference documentation for OBazl rules, providers, etc. is generated using Stardoc.

Running $ make will run the Stardoc processor and then copy the output to the appropriate src subdirectories.

Output is heavily customized; see Custom Output for more information.

The Stardoc rules are in stardoc/BUILD.bazel, templates in stardoc/templates/asciidoc.

  1. Overviews and indices are in the files listed in the header_template attribute of the stardoc rule, and are found in templates/asciidoc. E.g. the header for ocaml rules is templates/asciidoc/header_rules_ocaml.vm. If you add/change/delete a rule name, you need to edit the header.

  2. The input attrib of the the rules_ocaml stardoc target (in stardoc/BUILD.bazel) is @rules_ocaml//build:rules.bzl, which is the same extension file applications use to import the rules; it exports the publicly available rule names.

  3. Documentation is generated only for the rules listed in the symbol_names attribute of the stardoc targets, so the indices (in the header templates) must be (manually) kept in sync with this list.