Evergreen

wishlist: Antora-ize docs

Bug #1848524 reported by Ted Peterson
12
This bug affects 2 people
Affects Status Importance Assigned to Milestone
Evergreen
Fix Released
Wishlist
Unassigned
Evergreen 3.6-beta

Bug Description

As the Evergreen ILS docs are already in a Git repo and the excellent AsciiDoc format, we propose a wish list item to "Antora-ize" the docs directory tree. Hopefully this can start a discussion about Antora.

Antora, an OSS project of OpenDevise, helps manage docs as code, converting AsciiDoc documents to HTML with asciidoctor.js, and can maybe help target some of DIG's tasks on the Evergreen Documentation Needs page (improved automation, UI improvements, PDF generation with Antora 3.0, etc):
https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:documentation_needs

See:
https://antora.org
https://opendevise.com/blog/
https://asciidoctor.org/docs/asciidoctor.js

docs/wiki links can later be added within the staff and OPAC clients as has been requested:
https://bugs.launchpad.net/evergreen/+bug/1242717

Antora-ize TODO:
• Organize docs into section "modules": Antora docs are stored in a module structure:
https://opendevise.com/blog/standard-project-structure-for-docs/

• Configure different docs branches in git. See the MuleSoft and Antora docs for examples of how versions can be presented:
https://docs.mulesoft.com
https://docs.antora.org

• Setup Lunr search:
https://github.com/Mogztter/antora-lunr

• Update DIG workflow guide as appropriate
https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:how-to-contribute-documentation
Antora can be installed locally to maintain your own offsite copy of documentation (in-progress version branches, etc).

Antora Roadmap: https://docs.antora.org/antora/2.1/project/roadmap/

Ted Peterson (devted)
tags: added: documentation wishlist
Revision history for this message
Blake GH (bmagic) wrote :

Branch started here:
https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/blake/LP1848524_antora_ize_docs

Revision history for this message
Remington Steed (rjs7) wrote :

A few quick observations, which I haven't heard Blake mention yet:

Pros:
- Antora has a solution for our frequent broken page links (they call them "Page IDs").
- Antora requires a level of organization that I think would benefit us. Even if we don't choose to use Antora, we should consider adopting some of their practices.

Cons:
- Antora doesn't seem to have a way to add "Previous / Next" links, which we currently have on every docs page. They do have a persistent left navigation / table of contents, which serves a similar purpose, but not identical. We should decide if this difference is important for us.

Revision history for this message
Blake GH (bmagic) wrote :

Collab branch now (deleted the user branch)

collab/blake/LP1848524_antora_ize_docs

https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/blake/LP1848524_antora_ize_docs

Revision history for this message
Blake GH (bmagic) wrote :

For those of you following at home: Remington and I have been pushing lots of changes to that collab branch. I just pushed the search feature to it. Also, making note of some of the AsciiDoc errors during the build process:

asciidoctor: ERROR: item_status.adoc: line 66: include target not found: ../admin/turn-off-print-headers-firefox.adoc
asciidoctor: ERROR: item_status.adoc: line 68: include target not found: ../admin/turn-off-print-headers-chrome.adoc
asciidoctor: ERROR: intro_opensrf.adoc: line 1351: include target not found: python_client.py
asciidoctor: ERROR: end_matter.adoc: line 23: level 0 sections can only be used when doctype is book
asciidoctor: ERROR: end_matter.adoc: line 34: level 0 sections can only be used when doctype is book

Revision history for this message
Blake GH (bmagic) wrote :

Here are my thoughts right now:

Antora will automatically set the "title" of the browser page when the document has a "title" which is translated from the main heading line in the document. I've noticed that some of our documents start out with level 2 headers (Example):

Parts Level Hold
~~~~~~~~~~~~~~~~

Which is the "second" heading. The main heading needs to look like this:

Main Header
===========

We have a small issue here. As-is, the Antora pages will have HTML in the <head> block that looks like this:

<title>Untitled :: Evergreen Documentation</title>

We could write a script to automatically change all of our docs to have the main header. While we are at it, I was thinking that it would be nice to convert all of the headings to the "other" syntax. Like this:

From:

Parts Level Hold
~~~~~~~~~~~~~~~~

to:

=== Parts Level Hold ===

and

Placing Multiple Holds on Same Title
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
to
==== Placing Multiple Holds on Same Title ====

and

Holds Pull List
+++++++++++++++

to

===== Holds Pull List =====

It seems that we have skipped "Level 1" sometimes? Lifted from https://powerman.name/doc/asciidoc

Level 1
-------
Text.

Level 2
~~~~~~~
Text.

Level 3
^^^^^^^
Text.

Level 4
+++++++
Text.

Looking at our wiki:
https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:how-to-contribute-documentation

We direct people to https://powerman.name/doc/asciidoc for the correct syntax.

I assume in the cases where we don't have a main header we should? In those cases should we "upgrade" level 2 -> 1 and 3 -> 2 and 4 -> 3 ?

Also - a table of contents (per page) would be nice. The same script could also add the :toc: syntax directly below the main header.

In summary

1. Create a main header line for documents that don't have one (and upgrade the other headings up a level in those cases)
2. Convert the header style lines to moustache style (number of equal signs on each side)
3. Add a table of contents to each document where one doesn't appear.

Revision history for this message
Remington Steed (rjs7) wrote :

Blake, I agree with your suggestions. I've added a section to the DIG Style Guide wiki page so that DIG can discuss these Antora-related changes:

https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:dig_style_guide

As for your point #1, I'd call that a "bug" rather than a style change. Our old/current docs approach relies on the root files to use "leveloffset" when including certain files to correct the heading level mismatch. Let's take this opportunity to fix that. Your suggestion of "upgrading" those headings sounds good; that's exactly what the "leveloffset" approach did.

Revision history for this message
Blake GH (bmagic) wrote :

Remington: I think that #1 could have been on purpose. Reason is, the current documentation compile/html presentation will take pages as fragments and insert them "under" other pages. In those cases, the document starting with Level 2 was on purpose because the editor knew that it was going to be integrated into another document that already had the Level 1? Purely speculation.

Revision history for this message
Jane Sandberg (sandbergja) wrote :

One issue with the install instructions in the README:

  30 $ cd ui
  31 $ npm install
  32 $ gulp --tasks-simple
  33 $ gulp bundle

The two gulp commands usually fail with "bash: gulp: command not found" for me. We could have users specify the file to node_modules/gulp/bin/gulp.js when running these commands, but that seems like it could easily break, and is a lot of typing. :-)

Maybe we could add something like this to package.json:

"scripts": {
      "gulp-bundle": "gulp bundle"
 }

And then users could run `npm run gulp-bundle` and not have to worry about what binaries happen to be in their PATH.

And is there any purpose to the `gulp --tasks-simple` line, other than to confirm gulp installed correctly?

Revision history for this message
Jane Sandberg (sandbergja) wrote :

Also, I like the permalinks available for specific sections. I don't think we should require users to hover over the heading to be able to see that it's available though -- this will be inaccessible to some users, and will just be missed by a lot of readers who might need it. Maybe something we can resolve once the ui is broken out into its own git repo?

Revision history for this message
Blake GH (bmagic) wrote :

Just documenting it here in LP. The Evergreen UI repository has been created and all of the code from the Evergreen repo has been moved to this repo: https://git.evergreen-ils.org/?p=eg-antora.git;a=summary

As per Jane's suggestions, I added that "scripts" clause to the package.json file allowing a shortcut for gulp bundle. The README on the Evergreen repo was also updated to reflect this feature. That came in with commit 13bbc80e7d7

A note on the "Shared" folder. This is a bit of a mess. I believe it's "correct" when integrated into the old documentation build process but in Antora, I'm not sure. The first thing that threw me was "end_matter.adoc" having two level 0 headings:

= Licensing =
and
= Index =

In order for Antora to build properly, I had to relegate "Index" to level 1. No big deal, but I would like to know the implications of this file and these files:

licensing.adoc
index.adoc

Also - I just committed the work for the Acq module. Like we talked about, the heading levels were upgraded and the Table of Contents was added. I've built the result set and you can view them here:

http://antora.mobiusconsortium.org/prod/docs/latest/acquisitions/introduction.html

Revision history for this message
Jane Sandberg (sandbergja) wrote :

We can definitely get rid of the shared folder and move their contents to a different module. The idea was that we could use the same licensing statement and index-generating directives throughout all of the re-organized manuals. So the shared folder was meant to save us from copy/pasting and content drifting out of date. It doesn't really fit the antora model, so we should redistribute that content where it makes more sense.

BTW, I updated the branch with a few recent docs changes, so the antora branch doesn't get out of date

Revision history for this message
Remington Steed (rjs7) wrote :

I'll start working on the Cataloging nav file. Here are the steps that we seem to need for each section (using Blake's commit "Navigation: Acq is done" as an example):

- Add chapter labels to nav file items
- To match existing docs "chapter" level headings, combine adoc files as needed so that each "chapter" from the old docs structure has a single file linked from the nav
- Upgrade all heading levels in each adoc file so that the top-most heading is a "Level 1" heading (example: "= Chapter Name =")
- Add ":toc:" below top heading of each file

Revision history for this message
Remington Steed (rjs7) wrote :

I'm done with cataloging and now I'm working on the nav section called "System Configuration and Customization".

Revision history for this message
Jane Sandberg (sandbergja) wrote :

Some UI feedback from colleagues in my consortium:

* We're missing a section on command-line administration. One of my colleagues suggested that we have an antora module that corresponds to the current command line admin manual.

* They liked the link to the tabular release notes.

* A suggestion that we have some common left-side menus pre-expanded, so that there would be less clicking.

Revision history for this message
Remington Steed (rjs7) wrote :

Jane, I've been wondering how we would setup the topic manuals (such as Command Line Admin). That seems like the next problem to solve. After some basic research, it seems like we could keep them all in the same Antora "site" as separate "components". We would need a new layer of directories for those, like this:

docs-antora/site.yml
docs-antora/consolidated/antora.yml
docs-antora/acquisitions/antora.yml

Does anyone see a better way? Are there reasons to have separate Antora sites for the topic manuals?

Revision history for this message
Remington Steed (rjs7) wrote :

I'm working on the nav section "Using the Public Access Catalog".

Revision history for this message
Remington Steed (rjs7) wrote :

I'll also do the "Developer Resources" and "Getting Data from Evergreen" sections.

Revision history for this message
Blake GH (bmagic) wrote :

Taking "reports"

Revision history for this message
Remington Steed (rjs7) wrote :

I'm working on the "Serials" section.

Revision history for this message
Remington Steed (rjs7) wrote :

I'll do the "Circ" section. I think that's the last of the nav sections needing work.

We still need to figure out the topic manuals. And we could use lots of general review to look for broken things.

Revision history for this message
Remington Steed (rjs7) wrote :

I finished the "Circulation" section, so I think the nav related updates are done.

Next, we need lots of general review of the whole docs, looking for broken things.

We also need to setup the topic manuals. I'll give that a try using my suggestion in comment #15 above.

Revision history for this message
Blake GH (bmagic) wrote :
Download full text (6.4 KiB)

These are the current build errors:

asciidoctor: WARNING: skipping reference to missing attribute: 2
asciidoctor: WARNING: skipping reference to missing attribute: 3
asciidoctor: WARNING: skipping reference to missing attribute: 4
asciidoctor: WARNING: skipping reference to missing attribute: 2
asciidoctor: WARNING: skipping reference to missing attribute: 4
asciidoctor: WARNING: receipt_template_editor.adoc: line 206: no callout found for <1>
asciidoctor: WARNING: receipt_template_editor.adoc: line 207: no callout found for <2>
asciidoctor: WARNING: receipt_template_editor.adoc: line 208: no callout found for <3>
asciidoctor: WARNING: skipping reference to missing attribute: term
asciidoctor: WARNING: skipping reference to missing attribute: today
asciidoctor: WARNING: MARC_Editor.adoc: line 4: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: MARC_Editor.adoc: line 40: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: MARC_Editor.adoc: line 98: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: MARC_Editor.adoc: line 110: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: turn-off-print-headers-firefox.adoc: line 1: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: turn-off-print-headers-chrome.adoc: line 1: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: item_tags_cataloging.adoc: line 10: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: record_buckets.adoc: line 74: list item index: expected 1, got 4
asciidoctor: WARNING: record_buckets.adoc: line 75: list item index: expected 2, got 5
asciidoctor: WARNING: record_buckets.adoc: line 79: list item index: expected 1, got 6
asciidoctor: WARNING: record_buckets.adoc: line 83: list item index: expected 1, got 7
asciidoctor: WARNING: record_buckets.adoc: line 87: list item index: expected 1, got 8
asciidoctor: WARNING: record_buckets.adoc: line 88: list item index: expected 2, got 9
asciidoctor: WARNING: record_buckets.adoc: line 89: list item index: expected 3, got 10
asciidoctor: WARNING: record_buckets.adoc: line 107: list item index: expected 1, got 4
asciidoctor: WARNING: record_buckets.adoc: line 108: list item index: expected 2, got 5
asciidoctor: WARNING: record_buckets.adoc: line 109: list item index: expected 3, got 6
asciidoctor: WARNING: record_buckets.adoc: line 113: list item index: expected 1, got 7
asciidoctor: WARNING: record_buckets.adoc: line 117: list item index: expected 1, got 8
asciidoctor: WARNING: record_buckets.adoc: line 118: list item index: expected 2, got 9
asciidoctor: WARNING: record_buckets.adoc: line 119: list item index: expected 3, got 10
asciidoctor: WARNING: record_buckets.adoc: line 120: list item index: expected 4, got 11
asciidoctor: WARNING: record_buckets.adoc: line 121: list item index: expected 5, got 12
asciidoctor: WARNING: record_buckets.adoc: line 122: list item index: expected 6, got 13
asciidoctor: WARNING: record_buckets.adoc: line 123: list item index: expected 7, got 14
asciidoctor: WARNING: record_buckets.adoc: ...

Read more...

Revision history for this message
Blake GH (bmagic) wrote :

Also - it's on a new server now:

http://eg-docs.georgialibraries.org/prod/

Revision history for this message
Blake GH (bmagic) wrote :

Rebased to master

Revision history for this message
Blake GH (bmagic) wrote :

All,

I've pushed a few commits to the top. Namely, there is a new perl script to help aid the build process: generate_docs.pl. I've documented how to use that script in the README.adoc as well.

Hope this is helpful. Thoughts and feedback welcome! The script is working for me on the new eg-docs server - but that is the only test I've performed extensively. With more usage, we might find it needs updated, feel free to commit changes.

Revision history for this message
Deborah Luchenbill (deborah) wrote :

DIG has discussed and been involved in the direction of the development of Antora, and members have tested, made suggestions, and helped add things to it. We are in approval of moving forward with making the Antora version of the docs the official Evergreen docs.
-Debbie Luchenbill, <email address hidden>, DIG Chair

Galen Charlton (gmc)
Changed in evergreen:
status: New → Confirmed
importance: Undecided → Wishlist
milestone: none → 3.6-beta
assignee: nobody → Galen Charlton (gmc)
Revision history for this message
Galen Charlton (gmc) wrote :

I have pushed a somewhat squashed version of the branch to master for inclusion in 3.6, including follow-ups that

- move a couple straggler files to TechRef
- sync up the installation documentation
- tweak generate_docs.pl a bit so that it can work with fewer global requirements and no need for sudo
- implement the docs-antora => docs move
- add release notes

Thanks, Remington, Blake, Jane, and the rest of DIG!

Changed in evergreen:
assignee: Galen Charlton (gmc) → nobody
status: Confirmed → Fix Committed
Evergreen Bug Maintenance (bugmaster)
Changed in evergreen:
status: Fix Committed → Fix Released
Revision history for this message
Blake GH (bmagic) wrote :
Download full text (5.0 KiB)

Posting the build errors here for Andrea

asciidoctor: WARNING: actiontriggers.adoc: line 121: section title out of sequence: expected level 2, got level 3
asciidoctor: ERROR: latency.adoc: line 20: level 0 sections can only be used when doctype is book
asciidoctor: ERROR: latency.adoc: line 1: level 0 sections can only be used when doctype is book
asciidoctor: ERROR: latency.adoc: line 20: level 0 sections can only be used when doctype is book
asciidoctor: WARNING: describing_your_organization.adoc: line 163: invalid style for example block: Note
asciidoctor: WARNING: circulating_items_web_client.adoc: line 293: invalid style for example block: Note
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 59: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 72: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 91: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 96: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 119: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 125: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 131: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 139: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 169: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 175: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 183: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 189: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 201: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 209: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 213: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: reporter_evergreen_database.adoc: line 217: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: circulating_items_web_client.adoc: line 293: invalid style for example block: Note
asciidoctor: WARNING: actiontriggers.adoc: line 121: section title out of sequence: expected level 2, got level 3
asciidoctor: ERROR: latency.adoc: line 20: level 0 sections can only be used when doctype is book
asciidoctor: ERROR: latency.adoc: line 1: level 0 sections can only be used when doctype is book
asciidoctor: ERROR: latency.adoc: line 20: level 0 sections can only be used when doctype is book
a...

Read more...

Revision history for this message
Andrea Neiman (aneiman) wrote (last edit ):

Opened a new bug for the build errors: bug 2040326

To post a comment you must log in.
This report contains Public information  
Everyone can see this information.
Subscribing...

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.