On 11/09/2019 18:40, ajs6f wrote:
Adding it to the build means that the documented examples should always stay in step with the code it pulls from the tests and the must pass.Good idea to have a build step to help keep them up-to-date.I've used systems like this and they work well, but I think that we should do this after we move to a more graceful documentation build. In JENA-1755 Andy mentions Jekyll (which has come up before here) and some new features from INFRA for managing sites that should make it more automated. If this is the Jekyll in question: https://jekyllrb.com/docs/ do we have a good way to do a migration? Bruno, I seem to remember you having some experience with such a migration-- is that right? If so I would be happy to work with you to do this, if we all end up agreeing to it.
I'm hoping the bulk of conversion work is a perl script to redo the top of each file; Jekyll has short header section. Otherswise, the skeleton needs converting (one file) and there are bound to be "others" in small numbers. Less clear about styling but that's because I haven't looked at all.
I've mentioned Jekyll because I've used it (e.g. RDF Delta) and styled sites with it. It is the GH making it one of these base line systems developers have come across. The content is markdown which is the main point.
Other recommendations? There are a lot of static site generators, most of which look suitable. Pick your impl language is as good a factor as others!
Longevity, stability and maturity are important because we won't want to keep changing the site.
Andy
ajs6fOn Sep 7, 2019, at 12:52 PM, Andy Seaborne <[email protected]> wrote: On 05/09/2019 11:46, Claude Warren wrote:There were recently some comments about the lack of query builder documentation (https://issues.apache.org/jira/browse/JENA-1751), so taking that to heart I sat down to write some. Then I recalled I had seen a discussion on one of the other lists about generating examples for the web from example and test code. I was wondering a) if anybody else saw the discussion and if so do you remember where? b) if we should do something like that in Jena.Not the same thing but several module have "src-examples" so that code is available to be linked to. It gives the opportunity of addthme to the local IDE set so that are compiled.Adding it to the build means that the documented examples should always stay in step with the code it pulls from the tests and the must pass.Good idea to have a build step to help keep them up-to-date. There is the under-used jena-examples. Maybe that could be used.If there is interest I will see if I can find the other discussion. ClaudeAndy
