Changing script documentation from LaTeX/PDF to Markdown

For AI and campaign script related discussions and questions

Changing script documentation from LaTeX/PDF to Markdown

Postby Per » 19 Feb 2018, 01:34

The LaTeX documentation for the javascript API is, in my not so humble opinion, quite beautiful. However, it suffers from being not very accessible, and introducing a bunch of esoteric dependencies to the build system in order to generate this documentation. So I had a quick go at converting all the documentation into Markdown instead, and making it directly available through github.

The result:
https://github.com/perim/warzone2100/bl ... ripting.md

The commit:
https://github.com/perim/warzone2100/co ... 9e02879cfa

The disadvantage is that we would have to commit generated documents to git. However, I think in this case this is a better way to go.

Opinions?
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
 
Posts: 3745
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby NoQ » 20 Feb 2018, 19:10

I've been mostly thinking of doxygen as the better alternative. It works similarly to our LaTeX system (scans the source code and produces a bunch of plain-html files that can be put into the buildbot directory to minimize website maintenance work) but is definitely less esoteric. It might accidentally also help with documenting the rest of the code, not just the JS API. I don't know how hard it is to configure it, but i've been a relatively happy user for quite some time.

The markdown thing should work, updating via a simple grep command sounds easy. Is it possible to tell the buildbot to make pull requests when the markdown accidentally goes out of sync? (same with localization files)

I've preferred the single-page view here most of the time because i was navigating via ctrl+f anyway (this would be a bigger problem for doxygen).
User avatar
NoQ
Special
Special
 
Posts: 6146
Joined: 24 Dec 2009, 11:35
Location: /var/zone

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby Per » 20 Feb 2018, 20:11

We used to have doxygen for the source code... nobody ever used it, but there are some lingering files belonging to it in doc/ folder. I just find Doxygen very ugly, and it quickly turns into a mess of lots of tiny pages with undocumented stubs that nobody ever looks at, possibly hidden at some arcane URL that rarely gets updated. Or maybe there is a way to configure it to be pretty, I don't know.
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
 
Posts: 3745
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby Forgon » 21 Feb 2018, 01:33

Per wrote:The LaTeX documentation for the javascript API is, in my not so humble opinion, quite beautiful. However, it suffers from being not very accessible, and introducing a bunch of esoteric dependencies to the build system in order to generate this documentation. So I had a quick go at converting all the documentation into Markdown instead, and making it directly available through github. [...]
The disadvantage is that we would have to commit generated documents to git. [...]
Opinions?

I personally dislike both LaTex and Doxygen and thus embrace your idea.

Yet we should not have to commit generated documents to Git, but use a script that automatically generates the Markdown document from the source code. If I was informed about portability requirements, I might be able to help writing it.
Review my new green assignment crosshair cursor: ticket #4778
Forgon
Code contributor
Code contributor
 
Posts: 123
Joined: 07 Dec 2016, 22:23

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby Per » 21 Feb 2018, 09:44

The script that generates the Markdown from source code (at the end of Makefile.am):

doc/js-globals.md:
grep $(top_srcdir)/src/qtscript.cpp -e '//==' | sed 's/.*\/\/==//' > $(top_srcdir)/doc/js-globals.md
grep $(top_srcdir)/src/qtscriptfuncs.cpp -e '//==' | sed 's/.*\/\/==//' >> $(top_srcdir)/doc/js-globals.md
grep $(top_srcdir)/src/qtscript.cpp -e '//__' | sed 's/.*\/\/__//' > $(top_srcdir)/doc/js-events.md
grep $(top_srcdir)/src/qtscript.cpp -e '//--' | sed 's/.*\/\/--//' > $(top_srcdir)/doc/js-functions.md
grep $(top_srcdir)/src/qtscriptfuncs.cpp -e '//--' | sed 's/.*\/\/--//' >> $(top_srcdir)/doc/js-functions.md
grep $(top_srcdir)/src/qtscript.cpp -e '//;;' | sed 's/.*\/\/;;//' > $(top_srcdir)/doc/js-objects.md
grep $(top_srcdir)/src/qtscriptfuncs.cpp -e '//;;' | sed 's/.*\/\/;;//' >> $(top_srcdir)/doc/js-objects.md
grep $(top_srcdir)/data/base/script/campaign/libcampaign.js -e '.*//;;' | sed 's/\/\/;;//' > $(top_srcdir)/doc/js-campaign.md
test $(abs_top_srcdir) = $(abs_top_builddir) || cp $(top_srcdir)/doc/*.md doc/
.PHONY: doc/js-globals.md


The reason we'd commit the results is so that github can then serve as our documentation host, we wouldn't need to upload it anywhere else.
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
 
Posts: 3745
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby Forgon » 23 Feb 2018, 18:24

@Per: I have updated your patch so that it is no longer out-of-date, containing whitespace errors or preserving deprecated instructions.
Attachments
qtscript_markdown.patch
patch file created with `git format-patch`
(274.89 KiB) Downloaded 22 times
Review my new green assignment crosshair cursor: ticket #4778
Forgon
Code contributor
Code contributor
 
Posts: 123
Joined: 07 Dec 2016, 22:23

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby Per » 24 Feb 2018, 02:25

Thanks. Not sure if I see any difference in output from the empty newlines you added? https://github.com/perim/warzone2100/bl ... ripting.md But it doesn't hurt either, and readability looks better in the source, so I guess it is ok anyway.
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
 
Posts: 3745
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby Forgon » 24 Feb 2018, 13:04

Per wrote:Thanks. Not sure if I see any difference in output from the empty newlines you added? [...]

While some of these empty lines have no effect apart from creating more readable Markdown files, most are necessary: For conversion to HTML, all lists must be written in paragraphs of their own.

Markdown syntax:
Code: Select all
text
* list item
text

Generated HTML:
Code: Select all
<p>text
* list item
text</p>

Markdown syntax:
Code: Select all
text

* list item

text

Generated HTML:
Code: Select all
<p>text</p>

<ul>
<li>list item</li>
</ul>


<p>text</p>
Review my new green assignment crosshair cursor: ticket #4778
Forgon
Code contributor
Code contributor
 
Posts: 123
Joined: 07 Dec 2016, 22:23

Re: Changing script documentation from LaTeX/PDF to Markdown

Postby Per » 24 Feb 2018, 14:06

Change has been pushed. Now everyone please help proof-reading it, and someone please add support for it into the other build systems.
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
 
Posts: 3745
Joined: 03 Aug 2006, 19:39


Return to Scripting