[Evergreen-dev] Antora

[Galen Charlton]

Hi,

On Friday I merged to master the branch for LP#1848524, which adjusts the
Evergreen documentation to use the Antora site builder.  There are some
implications that developers should be aware of:

- The docs/RELEASE_NOTES* convention is not affected by the shift to
Antora. (At least, not yet; I could imagine that we might end up choosing
to fold the release notes into the Antora-built manual.)
- Similarly, docs/TechRef has been left alone, other than moving a couple
stray adoc files there.
- Otherwise, documents were moved (roughly speaking) from docs/foo/* to
docs/modules/foo/pages/*
- docs/topics/ contains an example of a topic-specific manual (for
acquisitions, in this case) that references a set of sections in the core
manual
- docs/README.adoc explains how to build the Antora site, while
generate_docs.pl automates most of it
- The new docs/ layout was not backported to rel_3_5 and earlier, so any
devs handling commits that include documentation should take note if they
backport such patches.
- There were some changes to the AsciiDoc markup conventions we use.
Hopefully Blake and DIG can expand on what I'm about to write, but the most
noticeable ones are:

* Change the headings from

Heading 1
========

to

= Heading 1 =

Rather than using "~~~", "^^^^", etc., adjust the number of equals signs to
control the heading's level.

* Adding ":toc:" below the top heading of each file
* For references, use

xref:reports:reporter_folder.adoc#reporter_creating_folders[Creating
Folders].

rather than

<<reporter_creating_folders,Creating Folders>>.

Regards,

Galen
-- 
Galen Charlton
Implementation and Services Manager
Equinox Open Library Initiative
phone:  1-877-OPEN-ILS (673-6457)
email:  gmc at equinoxInitiative.org
web:  https://equinoxInitiative.org
direct: +1 770-709-5581
cell:   +1 404-984-4366
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-dev/attachments/20200908/d6c07de1/attachment.html>