YetAnotherForum
Welcome Guest Search | Active Topics | Log In | Register

Documentation system
fagiano
#1 Posted : Monday, January 25, 2016 4:39:34 PM(UTC)
Rank: Advanced Member

Groups: Registered, Administrators
Joined: 6/11/2005(UTC)
Posts: 1,056

Thanks: 0 times
Was thanked: 78 time(s) in 60 post(s)
Hi,
Since I've put Squirrel source on GitHub I'd like also to create a repository for the documentation. However the current system that generates the documentation is a bit "intense".
Currently, Squirrel's documentation is generated starting from some xml file with custom syntax that I came out with. This files are then processed by some custom XSLT templates that generate DOCBOOK files that are then processed by an ancient version of DOCBOOK XSLT templates. Finally the outputs are fed to FOP(for PDF) and fed to HTML Help compiler(for CHM).
All of this is very tricky to setup and somewhat Windows oriented.
I'd like to streamline the process so that other people can generate docs without setting up too much crap on their system.

Does anybody know a good tool that would be suitable for docs?
Must be multi platform and more sane than my method. Ideally we should generate PDF, HTML and CHM. Personally I can live without CHM and I'd like to add "man pages".

ciao
Alberto
Follow me on Twitter @squirrellang
fagiano
#2 Posted : Monday, January 25, 2016 5:15:04 PM(UTC)
Rank: Advanced Member

Groups: Registered, Administrators
Joined: 6/11/2005(UTC)
Posts: 1,056

Thanks: 0 times
Was thanked: 78 time(s) in 60 post(s)
I did some research at first glance "reStructuredText" (that is part of python Docutils) looks nice, however looks like it needs LaTex for pdfs....mhhhh.

Alberto
Follow me on Twitter @squirrellang
Zylann
#3 Posted : Tuesday, January 26, 2016 6:26:54 PM(UTC)
Rank: Advanced Member

Groups: Registered
Joined: 6/25/2014(UTC)
Posts: 61
Location: France

Thanks: 1 times
Was thanked: 2 time(s) in 2 post(s)
Might sound a bit mainstream but, Doxygen?
It generates docs from comments in the code, however Squirrel hasn't such comments so I don't know if it suits you.
But the output look very nice, I think AngelScript's author uses that :)
fagiano
#4 Posted : Thursday, January 28, 2016 5:10:57 PM(UTC)
Rank: Advanced Member

Groups: Registered, Administrators
Joined: 6/11/2005(UTC)
Posts: 1,056

Thanks: 0 times
Was thanked: 78 time(s) in 60 post(s)
Personally, I really don't like comments as documentation. I rather have the two things separated.
Follow me on Twitter @squirrellang
fagiano
#5 Posted : Sunday, January 31, 2016 4:42:47 PM(UTC)
Rank: Advanced Member

Groups: Registered, Administrators
Joined: 6/11/2005(UTC)
Posts: 1,056

Thanks: 0 times
Was thanked: 78 time(s) in 60 post(s)
So, I started to convert the documentation to Sphinx it seems to fit the requirements, it is easy to use and well documented. When I'm done I'll create a repository on GitHub.
Follow me on Twitter @squirrellang
fagiano
#6 Posted : Sunday, February 14, 2016 1:37:27 PM(UTC)
Rank: Advanced Member

Groups: Registered, Administrators
Joined: 6/11/2005(UTC)
Posts: 1,056

Thanks: 0 times
Was thanked: 78 time(s) in 60 post(s)
So I finally converted all the doc to Sphinx, you can take a look here http://www.squirrel-lang.../squirreldoc/index.html
Now I'm wondering if would be better to create a new github repo called "squirredoc" or adding it to the main repo. Personally I'd rather have another repo but I saw that other projects mix code and doc together. Any thoughts about this?
Follow me on Twitter @squirrellang
absence
#7 Posted : Monday, February 15, 2016 10:23:34 PM(UTC)
Rank: Advanced Member

Groups: Registered
Joined: 8/23/2014(UTC)
Posts: 109
Man
Location: Northern Germany & Lincolnshire, U.K.

Thanks: 1 times
Was thanked: 10 time(s) in 10 post(s)
When they're separated you (the user) check for revision relations. When they're together, you expect code and doc always to match for all revisions. (Nothing's more annoying than outdated documentation bundled with code that moved past the doc)
Given that, branches and experimental code can get a pain if you want to do it right. In your case, I'd separate doc from code and create easy to follow correlations
Zylann
#8 Posted : Tuesday, February 16, 2016 12:15:00 AM(UTC)
Rank: Advanced Member

Groups: Registered
Joined: 6/25/2014(UTC)
Posts: 61
Location: France

Thanks: 1 times
Was thanked: 2 time(s) in 2 post(s)
Personally I like to have the doc built-in when getting a library.
Also, is there an offline version of the new documentation (PDF/HTML)?
fagiano
#9 Posted : Tuesday, February 16, 2016 2:51:39 PM(UTC)
Rank: Advanced Member

Groups: Registered, Administrators
Joined: 6/11/2005(UTC)
Posts: 1,056

Thanks: 0 times
Was thanked: 78 time(s) in 60 post(s)
Quote:
Personally I like to have the doc built-in when getting a library.

Yes, what I'd like is to have pdf & htmlhelp in the doc folder of the source and a separated github repo for the "raw sources" of the documentation. Is that what you mean?

Alberto
Follow me on Twitter @squirrellang
Zylann
#10 Posted : Tuesday, February 16, 2016 6:19:31 PM(UTC)
Rank: Advanced Member

Groups: Registered
Joined: 6/25/2014(UTC)
Posts: 61
Location: France

Thanks: 1 times
Was thanked: 2 time(s) in 2 post(s)
No, I meant everything in the same repo. I never considered splitting doc source and lib actually. What would be the advantages?
fagiano
#11 Posted : Friday, February 19, 2016 5:38:09 PM(UTC)
Rank: Advanced Member

Groups: Registered, Administrators
Joined: 6/11/2005(UTC)
Posts: 1,056

Thanks: 0 times
Was thanked: 78 time(s) in 60 post(s)
well, personally when I pull the source of a project I'd rather have a pdf than the source of the doc. But I could always provide the pdf download from somewhere else.
Follow me on Twitter @squirrellang
Users browsing this topic
Guest
Forum Jump  
You cannot post new topics in this forum.
You cannot reply to topics in this forum.
You cannot delete your posts in this forum.
You cannot edit your posts in this forum.
You cannot create polls in this forum.
You cannot vote in polls in this forum.

Clean Slate theme by Jaben Cargman (Tiny Gecko)
Powered by YAF 1.9.4 | YAF © 2003-2010, Yet Another Forum.NET
This page was generated in 0.107 seconds.