-
Notifications
You must be signed in to change notification settings - Fork 15
DocsReadme
This RTGOV wiki is the source of the Runtime Governance documents. We convert the asciidoc into an intermediate Docbook format, which then is used to create HTML and PDF versions. If you want to build these yourself you need to install asciidoc on your machine and check out the repository locally using:
git clone git@github.com:Governance/rtgov.wiki.git
Then go into the rtgov.wiki/<Name>/en-US directory, and run:
asciidoc -a docinfo -b docbook <Name>.asciidoc
Where <Name> can be DeveloperGuide, QuickStartGuide or UserGuide. This will produce a docbook formatted file called <Name>.xml. Now, go back up in the guide directory and run:
mvn clean install
and it will build HTML and PDF versions in the target/docbook/publish/en-US directory.
-
I spotted a typo, can I fix it?
Yes please help us maintain the documentation. Simply update the appropriate page right on github. Our nightly build will distribute the changes to docbook and the html and pdf versions.
-
How do I add an image?
Images cannot be uploaded through the github UI. Instead you need to add them to the
images
directory in the root of the rtgov.wiki repo and then push it up to github. You can then reference your image on the page usingimage::images/<myimage>.ext
. NOTE: Make sure to add an empty line before and after this image reference. -
How do add a numbering and references?
You should add a label -we use the convention <type>-<chapter>-<label>, i.e.
[[figure-gs-screenshot-of-the-ui]]
- , a title i.e..Welcome screen of the goverance ui.
and then the thing itself -for an image use something likeimage::images/rtgov.png[Screenshot of the Governance UI]
. The labelfigure-gs-screenshot-of-the-ui
can be used to link to this figure using<<figure-gs-screenshot-of-the-ui>>
. -
How do I add a chapter to the book in docbook?
We add chapters as different files, and then include them in the top level document, e.g.
UserGuide.asciidoc
file. At docbook generation time it will pull in the chapter into theUserGuide.xml
file. Also we add a link in the_Sidebar.asciidoc
page to have a link when looking at it at Github in wiki style.