Re: Proposal: Migrating docs to Asciibinder framework

Ronny Trommer <[email protected]> Wed, 25 Oct 2017 14:48:13 +0200
Newsgroups	gmane.network.opennms.general
Message-ID	<[email protected]>
Anything else we have to do here? Current status update what I did lately on the branch

- Added search
- Merged Minion into Horizon docs so we have just one distribution to make deployment easier
- Merged newly added Telemetryd daemon docs and JTI adapter docs from develop
- Merged fixes in JMX Configgenerator from develop
- Merged with latest develop

I have to start with some docs for the Netflow 5 Adapter[1]. How can we move forward? To keep the work mergeable gets more more expensive.

Regards Ronny

[1] https://issues.opennms.org/browse/HZN-1178


> On 27. Sep 2017, at 16:57, Ronny Trommer <[email protected]> wrote:
> 
> As Jesse suggested, I did some work on restructuring the content a little bit. Basic changes is, introducing a “Reference” section where I simplified the structure and put in the topics where we don’t have a good place for.
> 
> Just as a thought to get the left topic hierarchy a little bit shorter:
> 
> * we could move all the “Monitors”, “Collectors” in this section and reduce the “Service Assurance” and “Performance Datacollection” on the general concepts.
> * The ReST API would be a similar candidate for the Reference Section
> 
> So far
> 
>> On 26. Sep 2017, at 13:51, Ronny Trommer <[email protected] <mailto:[email protected]>> wrote:
>> 
>> Update:
>> 
>> I’ve got the ascii_binder_search_plugin deployed which is developed in the Gluster project. The plugin allows to search in a specific version of the documentation. By default the index everything in a local file but allow also more sophisticated things like ElasticSearch as backend. The indexing and generation of the search page is a separate step after you’ve packaged the documentation with asciibinder package.
>> 
>> I’ve published the default search page which comes from the project here:
>> 
>> 	https://docs.opennms.eu/horizon/search.html <https://docs.opennms.eu/horizon/search.html>
>> 	https://docs.opennms.eu/minion/search.html <https://docs.opennms.eu/horizon/search.html>
>> 
>> If you want to play with it:
>> 
>> I’ve built a docker image which allows to use it with our current documentation branch:
>> 
>> 	git clone https://github.com/OpenNMS/opennms.git <https://github.com/OpenNMS/opennms.git>
>> 	cd opennms
>> 	git checkout -b jira/NMS-9495 origin/jira/NMS-9495
>> 	docker run -v $(pwd):/usr/src/docs opennms/asciibinder package docs
>> 	docker run -v $(pwd)/docs:/usr/src/docs opennms/asciibinder-search -i front_end_indexer -v
>> 
>> The horizon/search.html and minion/search.html needs to be served through a web server. The files data_NMS-9495.json and versions.json contain the index data and the available versions.
>> 
>> Feedback welcome and have fun
>> 
>>> On 25. Sep 2017, at 15:49, Ronny Trommer <[email protected] <mailto:[email protected]>> wrote:
>>> 
>>> Agree, I’ve found three ways to implement search:
>>> 
>>> * OpenShift with a self implemented PHP page
>>> * Algolia which is an external provider for document indexing and search
>>> * AsciiBinder search plugin from the Gluster project
>>> 
>>> I’ll start investigating the current solutions. If someone else has some ideas, hints or tips - please let me know.
>>> 
>>>> On 22. Sep 2017, at 18:23, Jesse White <[email protected] <mailto:[email protected]>> wrote:
>>>> 
>>>> One thing that's missing from the AsciiBinder layout is the ability to search. With the current single document layout, I find myself using Ctrl+F and searching for keywords to locate the content, but this is no longer possible with the new layout.
>>>> 
>>>> The OpenShift documentation at https://docs.openshift.com/online/welcome/index.html <https://docs.openshift.com/online/welcome/index.html>, also based on AsciiBinder, provides this capability. Perhaps we could implement something similar?
>>>> 
>>>> -Jesse
>>>> 
>>>> 
>>>> On 09/19/2017 05:37 PM, Ronny Trommer wrote:
>>>>> Status Update
>>>>> 
>>>>> I have cleaned up the branch and removed the old opennms-doc directory from the branch. I’ve added also a first minimal stylesheet to look more like something OpenNMS-ish. We have Wednesday evening our OpenNMS internal sprint meeting and I’ll bring this topic up, so we can decide how to move forward.
>>>>> 
>>>>> Here are the things which reflect the current status of the branch jira/NMS-9495:
>>>>> 
>>>>> - Migrate everything in opennms-doc directory to AsciiBinder which is now the docs directory: DONE
>>>>> - Merge user/admin/developer docs to make it easier to find things: DONE
>>>>> - Deploy the current state to a public website for testing[1][2]: DONE
>>>>> - Add deployment mechanism to Bamboo and auto-publish on release (OPEN)
>>>>> 
>>>>> Suggestions as next steps when we have it migrated:
>>>>> 
>>>>> - Cleanup our release notes. we only need the Changelog and What’s new for the current version. For the reason the docs are versioned along with the software the history will build up by himself. Currently we drag the whole history of versions through our docs
>>>>> - Brainstorm and rethink the generic structure, we have now all in one place and we need to refactor things to make it easier to navigate and more obvious to find things you are looking for
>>>>> - Refactor* most important guides like the installation in better usable use-case driven Step-by-Step walkthroughs, for example:
>>>>>  	- “How to install on CentOS”
>>>>> 	- “How to create Surveillance View”
>>>>> 	- “How to create Wallboard for Screen Rotation”
>>>>> 	- “How to manage Node in a Requisition”
>>>>> 	- “How to add a new service monitor”
>>>>> 	- “How to collect performance data from a SNMP device"
>>>>> - Remove screenshots as much as we can and describe it instead to increase maintainability, e.g. like AWS CodeDeploy[3]
>>>>> - We have to think about the ReST API documentation, currently it is manually and we should definitely consider to use something like Swagger[4], RAML[5] or API Blueprint[6], the current manual created ReST API documentation is outdated and does not contain anything about the new introduced v2 API
>>>>> 
>>>>> Please feel free happy to get your feedback about it and if you are interested to contribute in one of the topics. I personally would prefer to move quickly from a “migrating something from tech A to B task" to a more content and structure driven work mode, content matters and there are a lot of interesting things to do :D
>>>>> 
>>>>> So far with greetings from Germany
>>>>> 
>>>>> [1] https://docs.opennms.eu/horizon/NMS-9495/about/index-opennms.html <https://docs.opennms.eu/horizon/NMS-9495/about/index-opennms.html>
>>>>> [2] http://docs.internal.opennms.eu/minion/NMS-9495/about/index-minion.html <http://docs.internal.opennms.eu/minion/NMS-9495/about/index-minion.html>
>>>>> [3] http://docs.aws.amazon.com/codedeploy/latest/userguide/tutorials-windows-update-and-redeploy-application.html#tutorials-windows-update-and-redeploy-application-deploy-updates-console <http://docs.aws.amazon.com/codedeploy/latest/userguide/tutorials-windows-update-and-redeploy-application.html#tutorials-windows-update-and-redeploy-application-deploy-updates-console>
>>>>> [4] https://swagger.io/docs/specification/about/ <https://swagger.io/docs/specification/about/>
>>>>> [5] https://raml.org <https://raml.org/>
>>>>> [6] https://apiblueprint.org/documentation/ <https://apiblueprint.org/documentation/>
>>>>> 
>>>>> *When I say refactoring, that always means not just adding stuff also deleting, the goal after refactoring is having less :)
>>>>> 
>>>>>> On 13. Sep 2017, at 01:54, Ronny Trommer <[email protected] <mailto:[email protected]>> wrote:
>>>>>> 
>>>>>> 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 <http://asciidoctor.org/>
>>>>>> [2] http://www.asciibinder.org <http://www.asciibinder.org/>
>>>>>> [3] https://wiki.opennms.org/wiki/Proposals/AsciiBinder <https://wiki.opennms.org/wiki/Proposals/AsciiBinder>
>>>>>> [4] https://github.com/OpenNMS/opennms/tree/jira/NMS-9495 <https://github.com/OpenNMS/opennms/tree/jira/NMS-9495>
>>>>>> [5] https://issues.opennms.org/browse/NMS-9495 <https://issues.opennms.org/browse/NMS-9495>
>>>>>> [6] https://docs.opennms.eu/horizon/NMS-9495/about/index.html <https://docs.opennms.eu/horizon/NMS-9495/about/index.html>
>>>>>> [7] https://docs.opennms.eu/minion/NMS-9495/about/index.html <https://docs.opennms.eu/minion/NMS-9495/about/index.html>
>>>>>> [8] http://docs.opennms.org/helm/branches/master/helm/latest/welcome/index.html <http://docs.opennms.org/helm/branches/master/helm/latest/welcome/index.html>
>>>>>> [9] https://chat.opennms.com/opennms/channels/opennms-discussion <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://slashdot.org/>! http://sdm.link/slashdot_______________________________________________ <http://sdm.link/slashdot_______________________________________________>
>>>>>> Please read the OpenNMS Mailing List FAQ:
>>>>>> http://www.opennms.org/index.php/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 <https://lists.sourceforge.net/lists/listinfo/opennms-discuss>
>>>>> 
>>>>> 
>>>>> ------------------------------------------------------------------------------
>>>>> Check out the vibrant tech community on one of the world's most
>>>>> engaging tech sites, Slashdot.org <http://slashdot.org/>! http://sdm.link/slashdot <http://sdm.link/slashdot>
>>>>> 
>>>>> _______________________________________________
>>>>> Please read the OpenNMS Mailing List FAQ:
>>>>> http://www.opennms.org/index.php/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 <https://lists.sourceforge.net/lists/listinfo/opennms-discuss>
>>>> ------------------------------------------------------------------------------
>>>> Check out the vibrant tech community on one of the world's most
>>>> engaging tech sites, Slashdot.org <http://slashdot.org/>! http://sdm.link/slashdot_______________________________________________ <http://sdm.link/slashdot_______________________________________________>
>>>> Please read the OpenNMS Mailing List FAQ:
>>>> http://www.opennms.org/index.php/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 <https://lists.sourceforge.net/lists/listinfo/opennms-discuss>
>>> ------------------------------------------------------------------------------
>>> Check out the vibrant tech community on one of the world's most
>>> engaging tech sites, Slashdot.org <http://slashdot.org/>! http://sdm.link/slashdot_______________________________________________ <http://sdm.link/slashdot_______________________________________________>
>>> Please read the OpenNMS Mailing List FAQ:
>>> http://www.opennms.org/index.php/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 <https://lists.sourceforge.net/lists/listinfo/opennms-discuss>
>> ------------------------------------------------------------------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org <http://slashdot.org/>! http://sdm.link/slashdot_______________________________________________ <http://sdm.link/slashdot_______________________________________________>
>> Please read the OpenNMS Mailing List FAQ:
>> http://www.opennms.org/index.php/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
>

------------------------------------------------------------------------------
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, 529 B)