[Evergreen-dev] Antora
Galen Charlton
gmc at equinoxinitiative.org
Tue Sep 8 12:01:23 EDT 2020
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>
More information about the Evergreen-dev
mailing list