Re: [rdf4j-dev] archive site

[Michael Grove <mike@xxxxxxxxxxx>]

On Fri, Aug 19, 2016 at 6:08 AM, Rick Moynihan <rick.m@xxxxxxxxxx> wrote:
> On 19 August 2016 at 00:54, Jeen Broekstra <jeen.broekstra@xxxxxxxxx> wrote:
>>
>> On 18/08/16 23:12, Nikola Petrov wrote:
>>
>> For the documentation, I think that something based on sphinx or jekyll
>> will be much more enjoyable in the long run.
>>
>> I like sphinx better but anything that supports changing the
>> documentation through pull requests is miles ahead of wordpress.
>>
>> I quite agree. I wasn't familiar with either Sphinx or Jekyll, but I was
>> thinking of using something along those lines.
>>
>> AsciiDoc (http://asciidoc.org/) stands out for me. There's several other
>> Eclipse project using it and from what I've read it comes with a great
>> toolchain and good support. It's like DocBook, but without the aggrevation
>> of having to edit XML (not to mention shout and kick at the tools to get
>> them to cooperate).
>
>
> I've used Jekyll in the past, it works - no real complaints with that
> option.
>
> If you're intending to do formal documentation I was going to suggest
> looking at AsciiDoc (not used it though)...  I did use docbook a long time
> ago, and thought it was pretty good - but the XML is a pain, and as far as I
> recall the XSLT/DSSL styling is pretty complex if you want to edit it.

We use asciidoc for our documentation, it's been working pretty well
so far for us.

>
> Not sure how well a doc site would play with Jekyll etc though...
>
> I've seen quite a lot of sites using
> http://docs.readthedocs.io/en/latest/index.html which seems like a very easy
> github friendly hosted option.  Personally though I find their documentation
> styling pretty horrible.  Not sure if that can be easily changed.
>
> Regarding the archive site, one thing to bear in mind is that it contains
> about 2gb of javadocs in a git repo (because of github pages); so it's a bit
> unweildy to work in that repo.  It might be worth considering a different
> sub domain for the non-legacy user docs.  We could perhaps share the
> HTML/styling/nav across the doc/archive site if we really wanted; but it
> would most likely need to be maintained/synchronised by hand.
>
> R.
>
>>
>>
>> And indeed putting the documentation in a git repo is an absolute must, I
>> think.
>>
>> The main site ofc can remain in wordpress
>>
>> Yes, for a download page or a news announcement simple Wordpress is much
>> easier.
>>
>>
>> Jeen
>>
>>
>> _______________________________________________
>> rdf4j-dev mailing list
>> rdf4j-dev@xxxxxxxxxxx
>> To change your delivery options, retrieve your password, or unsubscribe
>> from this list, visit
>> https://dev.eclipse.org/mailman/listinfo/rdf4j-dev
>>
>
>
> _______________________________________________
> rdf4j-dev mailing list
> rdf4j-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe from
> this list, visit
> https://dev.eclipse.org/mailman/listinfo/rdf4j-dev
>