Generator for offline documentation

[t-paul]

Outline

The user manual for OpenSCAD is maintained at Wikibooks. This is a nice solution as everybody with a Wikipedia account can help improving it. The drawback is that it's only available online. The "Print Version" accessible there needs special work and duplicates part of the information.

It would be very useful if generating an offline version that could be shipped with OpenSCAD could be automated.

Details

Wikipedia allows the export of data via a simple interface (https://en.wikipedia.org/wiki/Help:Export)

This is probably mainly intended to be the source for backups and/or for transferring data from one installation to another. There's big list of converters around, most seem to target the import into another wiki software but some will convert to other file formats already. (https://www.mediawiki.org/wiki/Alternative_parsers)

The manual export is easily done by calling https://en.wikibooks.org/wiki/Special:Export and entering "OpenSCAD_User_Manual" into the "Add pages from category". This exports all the text content into one big XML file.

The ideal option would be an automated way to convert this XML file into different formats. As first step, to make it usable as off-line documentation, the target would probably be either static HTML that could be shipped with OpenSCAD or maybe PDF.

It needs investigating if that actual programming is required, or if the existing tools are maybe already sufficient for that. So the specific tasks could be one of

1. write a script that does all the conversion and image downloading

2. write a simple script to just run various existing tools

3. go though the wiki pages of the manual and adjust some of the
   text so it works nicely with some existing tool

4. use a tool or write a script to scrape the HTML representation from Wikibooks

5. something else, we did not see yet...

Ideally that should run on Linux so it could be integrated into one of the automatic build servers (e.g. Travis). A manual solution that is just started now an then would also be a nice thing.

Challenges:

• Investigate current status of available converters
• Optional: Integrate the solution into the OpenSCAD build process

Expected Outcome

• An offline user manual that can be included in OpenSCAD releases.

Project Properties

Skills

• Programming language is python (or some other widely used scripting language... make a suggestion!)

Difficulty

Easy

Additional information

• Script for scraping the WikiPages as HTML by (runsun) - Forum discussion - Github Repository
• Maybe also look at the related Cheat Sheet issue

---

Mentors: Marius Kintel (IRC: kintel), Torsten Paul (IRC: teepee)

[ixil]

see openscad/openscad#2206 (comment)_
or https://github.com/ixil/openscad_offliner

[shruti-tanpure]

Hey! I would like to work on this issue.

[t-paul]

That's still possible, with the deadline approaching fast and other students having quite a head start, you may need to get into the topic in a very focused way.

[shruti-tanpure]

Okay! Thank you @t-paul