docs_obazl

dev:

Install and configure jekyll. I don’t remember how I did this to get started, but I probably followed stuff like this: Using Jekyll, Asciidoctor and GitHub Pages for Static Site Creation

Edit directly in docs/src

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

Site is at localhost:4000/docs_obazl/

Online at https://obazl.github.io/docs_obazl/

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.

See also Getting started with the Documentation Theme for Jekyll

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:

:page-layout: page_tools_opam
:page-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.

Github Actions

link:https://jekyllrb.com/docs/continuous-integration/github-actions/

jekyll-action-ts