Documentation with integration tests

[jamesaoverton]

trafficstars

I'd like to move forward with documentation for COB -- I'm actually really excited about doing that. Let me know if you disagree with this plan.

Summary: I'd like to follow the example of ROBOT docs, where the docs are also executable integration tests. This ensures that our examples always actually run successfully. And I'd like to write the docs in such a way that it's easy to convert them to slides with longer discussion in notes (untested).

• a new docs/ directory
• a Markdown file for each topic/chapter
  • format Markdown for GitHub Pages
  • also try to support reveal.js to convert to slides
  • also try to support Pandoc to convert to lots of other formats
  • include example code in fenced code blocks with {.foo} annotations: Turtle, SPARQL
  • include command-line examples to run against those code blocks
• docs/slides.html using reveal.js to load the Markdown files
• a script to extract code blocks as files
• a script to run the CLI examples as integration tests
  • test under different triplestores: Jena, Blazegraph
• a Makefile to run conversions and tests

Initial list of topics:

• introduction
• top-level classes and relations
• characteristics
• information
• planned processes
• measurement data

[bpeters42]

This sounds awesome James!

One thing to consider is the different audiences we have, and the different kinds of information they need. Minimally:

• Ontology *developers *that are considering to move towards using COB as an upper layer, and want technical information
• Ontology *consumers *that want to see the benefits of using ontologies based on COB, and want examples of inference
• OBO folks that want to present what COB is in 3 slides when they give a presentation

On Mon, May 11, 2020 at 9:39 AM James A. Overton [email protected] wrote:

I'd like to move forward with documentation for COB -- I'm actually really excited about doing that. Let me know if you disagree with this plan.

Summary: I'd like to follow the example of ROBOT docs, where the docs are also executable integration tests. This ensures that our examples always actually run successfully. And I'd like to write the docs in such a way that it's easy to convert them to slides with longer discussion in notes (untested).

• a new docs/ directory
• a Markdown file for each topic/chapter
  • format Markdown for GitHub Pages
  • also try to support reveal.js https://github.com/hakimel/reveal.js to convert to slides
  • also try to support Pandoc to convert to lots of other formats
  • include example code in fenced code blocks with {.foo} annotations: Turtle, SPARQL
  • include command-line examples to run against those code blocks
• docs/slides.html
• a script to extract code blocks as files
• a script to run the CLI examples as integration tests
  • test under different triplestores: Jena, Blazegraph
• a Makefile to run conversions and tests

Initial list of topics:

• introduction
• top-level classes and relations
• characteristics
• information
• planned processes
• measurement data

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/OBOFoundry/COB/issues/73, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADJX2IQVIGW65WSRKM5JHB3RRAS3DANCNFSM4M6CBFPA .

-- Bjoern Peters Professor La Jolla Institute for Allergy and Immunology 9420 Athena Circle La Jolla, CA 92037, USA Tel: 858/752-6914 Fax: 858/752-6987 http://www.liai.org/pages/faculty-peters

[cmungall]

I love the robot system!

But it seems overkill here? Maybe I'm suffering a failure of imagination but I'm not sure how much integrated testing on the docs is required. Isn't markdown enough?

I'm imagining something like the SIO docs:

https://github.com/MaastrichtU-IDS/semanticscience/wiki/Design-Patterns

e.g

https://github.com/MaastrichtU-IDS/semanticscience/wiki/DP-Biochemistry

These aren't valid OWL - labels are used in place of IRIs, and there are elipses ... but it's pretty good at giving the flavor of how the classes and properties are meant to be used.

We could also give example robot templates and dosdps

Maybe start with plain markdown and see how far we get?

we've also used rtd and mk-docs in other projects. Developers are faimilar with the rtd style

I would love to see some kind of improved OWLDoc though. COB is small enough it could be turned into a nice one-page doc like: https://www.w3.org/TR/vocab-ssn/

And this kind of doc would be easy to turn into a paper :-)

[cmungall]

@bpeters42

Ontology *developers *that are considering to move towards using COB as an upper layer, and want technical information

We definitely want to support this, but I'm imagining the first priority will be a lot of the main/core OBO ontologies (here defined as those with >=1 root that is equivalent to a COB class), and we are kind of doing this work for them, via curating cob-to-external?

One thing that might be useful is to work with core ontologies to give us a broad sample of 5-20 classes that are somehow 'representative'. We could then make seed files from these and use robot extract as part of the integration tests to build a 'meso-cob' (smaller than megacob which is all compliant ontologies merged in) which would make a really nice demonstrator, tractable as a demo that could be done in an old docker container...

• Ontology consumers that want to see the benefits of using ontologies based on COB, and want examples of inference

Yes! tbh most of the inference we get will be coherency checking rather than new inferences so maybe not that thrilling to most consumers. I think the main win will be 'it looks right'

• OBO folks that want to present what COB is in 3 slides when they give a presentation

yep!

[jamesaoverton]

My two main points are:

• lots of concrete examples
• every example should be tested: this can be a pain at first but pays big dividends, like integration testing in general

The other things I mentioned are just things I want to try. I'd like one set of documentation that we can pull apart into multiple "layers" suited for different audiences, as you both mentioned. Maybe it will work and maybe it won't.

[bjonnh]

I think it is a great idea.

Having the documentation accessible to different audiences is a must have, and it can probably be solved with a creatively crafted index page that directs people to what they are interested in.

If in the process, we can have a documentation system that can be used easily on other ontologies or ontology tools, that would be great.

[jamesaoverton]

This repo is an example of what I have in mind: https://github.com/jamesaoverton/cob-data-demo