Re: documentation and examples

[Rob Vesse]

+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"  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  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

[Andy Seaborne]

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  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

[ajs6f]

>> 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  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

[Andy Seaborne]

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

documentation and examples

[Claude Warren]

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

LinkedIn: http://www.linkedin.com/in/claudewarren