Proposal: Migrating docs to Asciibinder framework

Ronny Trommer <[email protected]> Wed, 13 Sep 2017 01:54:59 +0200
Newsgroups	gmane.network.opennms.general
Message-ID	<[email protected]>
Hello Everyone,

I’ve worked during DevJam 2017 to migrate our documentation from the plain Java based AsciiDoctor [1] to the AsciiBinder framework [2]. It addresses some more publishing and managing docs. It is used in projects like OpenShift, Atomic and is currently also in a evaluation phase for Fedora. The proposal is a little bit more described in the Wiki [3].

I’ve finished and cleaned up the work and you can find the proposed new structure in the branch lira/NMS-9495 [4][5]. To build the docs you need to install a ruby gem asciibinder. The new documentation structure is moved from opennms-docs which was build by maven into the docs folder.

Once you have it installed asciibinder you can clone the opennms git repo, change into the docs directory and run asciibinder package. If you want I’ve published the HTML output a public location [6][7]. So you can play around with.

Other than migration, I’ve noticed it is hard to find things, so I’ve decided to merge the install, admin and user guide. What we have noticed, we should reconsider and consolidate the overall structure without getting the overall structure too deep.

A first goal could be to publish the documentation similar as we did with Helm[8]

If you want to join in or want to give some feedback please let me know, I’m hanging out in the chat [9] and happy to talk about it. PRs against the branch are always welcome so feel free :)

Ronny

[1] http://asciidoctor.org
[2] http://www.asciibinder.org
[3] https://wiki.opennms.org/wiki/Proposals/AsciiBinder
[4] https://github.com/OpenNMS/opennms/tree/jira/NMS-9495
[5] https://issues.opennms.org/browse/NMS-9495
[6] https://docs.opennms.eu/horizon/NMS-9495/about/index.html
[7] https://docs.opennms.eu/minion/NMS-9495/about/index.html
[8] http://docs.opennms.org/helm/branches/master/helm/latest/welcome/index.html
[9] https://chat.opennms.com/opennms/channels/opennms-discussion

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot

_______________________________________________
Please read the OpenNMS Mailing List FAQ:
http://www.opennms.org/index.php/Mailing_List_FAQ

opennms-discuss mailing list

To *unsubscribe* or change your subscription options, see the bottom of this page:
https://lists.sourceforge.net/lists/listinfo/opennms-discuss
signature.asc (application/pgp-signature, 496 B)