You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jena.apache.org by Claude Warren <cl...@xenei.com> on 2019/09/05 10:46:25 UTC
documentation and examples
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.
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.
If there is interest I will see if I can find the other discussion.
Claude
--
I like: Like Like - The likeliest place on the web
<http://like-like.xenei.com>
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: documentation and examples
Posted by Rob Vesse <rv...@dotnetrdf.org>.
+1 for Jekyll
It's also quite conducive to scripting workflows around it. For example with Airline I have scripts that help publish the latest version of the Javadoc along with some Jekyll templating in my nav that allows hosting multiple versions of the Javadocs easily.
Rob
On 11/09/2019, 22:00, "Andy Seaborne" <an...@apache.org> wrote:
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
>
> ajs6f
>
>> On Sep 7, 2019, at 12:52 PM, Andy Seaborne <an...@apache.org> 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.
>>> Claude
>>
>> Andy
>>
>
Re: documentation and examples
Posted by Andy Seaborne <an...@apache.org>.
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
>
> ajs6f
>
>> On Sep 7, 2019, at 12:52 PM, Andy Seaborne <an...@apache.org> 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.
>>> Claude
>>
>> Andy
>>
>
Re: documentation and examples
Posted by ajs6f <aj...@apache.org>.
>> 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.
ajs6f
> On Sep 7, 2019, at 12:52 PM, Andy Seaborne <an...@apache.org> 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.
>> Claude
>
> Andy
>
Re: documentation and examples
Posted by Andy Seaborne <an...@apache.org>.
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.
>
> Claude
Andy