Changing script documentation from LaTeX/PDF to Markdown

For AI and campaign script related discussions and questions
Post Reply
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
Posts: 3780
Joined: 03 Aug 2006, 19:39

Changing script documentation from LaTeX/PDF to Markdown

Post by Per »

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?
User avatar
NoQ
Special
Special
Posts: 6226
Joined: 24 Dec 2009, 11:35
Location: /var/zone

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by NoQ »

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).
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
Posts: 3780
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by Per »

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.
Forgon
Code contributor
Code contributor
Posts: 298
Joined: 07 Dec 2016, 22:23

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by Forgon »

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.
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
Posts: 3780
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by Per »

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.
Forgon
Code contributor
Code contributor
Posts: 298
Joined: 07 Dec 2016, 22:23

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by Forgon »

@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 382 times
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
Posts: 3780
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by Per »

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.
Forgon
Code contributor
Code contributor
Posts: 298
Joined: 07 Dec 2016, 22:23

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by Forgon »

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>
Per
Warzone 2100 Team Member
Warzone 2100 Team Member
Posts: 3780
Joined: 03 Aug 2006, 19:39

Re: Changing script documentation from LaTeX/PDF to Markdown

Post by Per »

Change has been pushed. Now everyone please help proof-reading it, and someone please add support for it into the other build systems.
Post Reply