documentation generator

[stuckyb]

It would be cool if OntoPilot could automatically generate user documentation for an ontology. E.g., a document of terms and term definitions.

[jdeck88]

+1 A few approaches off the top of my head:

XSLT style sheet --- i've done this before and aside from a super nasty syntax works ok. This is what i used to generate: http://www.biscicol.org/terms/ (ah, the memories)

Using something like readthedocs and building from there (extra cruft to apply to build but does make some appealing documentation). Uses a markdown like syntax to build document... another example that i've done: http://fims.readthedocs.io/en/stable/

Generate HTML directly from the input source files (this is i think how the darwin core reference page is built-- as i recall Tuco builds these from an access database (http://rs.tdwg.org/dwc/terms/)

I'd be in favor of the most simple approach (HTML directly-- approach #3). but each of them has their uses/advantages and really up to you Brian...

John

On Tue, Jun 6, 2017 at 11:39 AM, stuckyb notifications@github.com wrote:

It would be cool if OntoPilot could automatically generate user documentation for an ontology. E.g., a document of terms and term definitions.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/stuckyb/ontopilot/issues/76, or mute the thread https://github.com/notifications/unsubscribe-auth/ABGdxblXsRYStX7OfVGNgiAruNbH1oBcks5sBZzogaJpZM4Nxv0R .

-- John Deck (541) 914-4739

[stuckyb]

Thanks, John! Great suggestions.

Does readthedocs have to be hosted on their official site?

As another option, what would you think about generating markdown directly (very simple syntax), and then using a tool like pandoc to generate any desired output format (PDF, HTML, etc.)? This would be similar to the reathedocs approach, I think, but might offer even more flexibility. The readthedocs format is very nice, though.

On 06/06/2017 02:53 PM, John Deck wrote:

+1 A few approaches off the top of my head:

XSLT style sheet --- i've done this before and aside from a super nasty syntax works ok. This is what i used to generate: http://www.biscicol.org/terms/ (ah, the memories)

Using something like readthedocs and building from there (extra cruft to apply to build but does make some appealing documentation). Uses a markdown like syntax to build document... another example that i've done: http://fims.readthedocs.io/en/stable/

Generate HTML directly from the input source files (this is i think how the darwin core reference page is built-- as i recall Tuco builds these from an access database (http://rs.tdwg.org/dwc/terms/)

I'd be in favor of the most simple approach (HTML directly-- approach #3). but each of them has their uses/advantages and really up to you Brian...

John

On Tue, Jun 6, 2017 at 11:39 AM, stuckyb notifications@github.com wrote:

It would be cool if OntoPilot could automatically generate user documentation for an ontology. E.g., a document of terms and term definitions.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/stuckyb/ontopilot/issues/76, or mute the thread

https://github.com/notifications/unsubscribe-auth/ABGdxblXsRYStX7OfVGNgiAruNbH1oBcks5sBZzogaJpZM4Nxv0R .

-- John Deck (541) 914-4739

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/stuckyb/ontopilot/issues/76#issuecomment-306582766, or mute the thread https://github.com/notifications/unsubscribe-auth/ADKD764Il7I5qJvKsuX4XmhfqXk1DhRUks5sBaA2gaJpZM4Nxv0R.

[stuckyb]

Making good progress on this. As a note to self, I shouldn't forget to incorporate the documentation components into the functional testing.

[stuckyb]

This feature is getting close. Documentation generation with both HTML and Markdown output is implemented, and functional testing now includes documentation generation. The last big piece is finishing the layout and CSS styles for HTML output.