Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [rdf4j-dev] archive site
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.

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


Back to the top