Offline documentation

[pfelecan]

How can I generate the documentation of the project offline ?
There are situations when I'm working offline and need to access the documentation.
There are also some issues when GitHub is slow or non responsive.
Finally, sometimes I'm not using the head of the tree and the documentation advanced in regard with the version that I'm using.
Thank you in advance of the generous soul who can give me the recipe to this endeavor.

[RAMilewski]

It's not as pretty as the wiki, but the documentation is actually just comments in the .scad files. @revarbat may be able to suggest how to generate the HTML files locally using his docsgen utility. I tried that once and failed, but I didn't spend much time trying.

[revarbat]

To just download the BOSL2 wiki locally, so you can view it offline, you can do the following:

1. Install a multi-file aware MarkDown viewer/editor. On Mac, I recommend Typora.
2. Clone the GitHub BOSL2 wiki repo locally. git clone https://github.com/BelfrySCAD/BOSL2.wiki.git
3. Open the BOSL2.wiki/Home.md file with your MarkDown viewer.

To generate a local copy of the docs from sources, follow these steps:

1. Install a MarkDown viewer/editor. On Mac, I recommend Typora.
2. Install a recent Python version.
3. Install pip and setuptools if needed. Recent Python versions don't need this step.
4. pip install openscad_docsgen
5. Clone the GitHub BOSL2 repo locally, if you haven't already. git clone https://github.com/BelfrySCAD/BOSL2.git
6. cd BOSL2
7. Clone the GitHub BOSL2.wiki repo locally. git clone https://github.com/BelfrySCAD/BOSL2.wiki.git
8. Run docs generation in the BOSL2 directory: openscad-docsgen
9. Wait a few minutes.
10. Run tutorial generation in the BOSL2 directory: openscad-mdimggen
11. Open BOSL2.wiki/Home.md with your MarkDown viewer/editor.

To nuke the docs from orbit, and regenerate EVERYTHING:

1. Install a MarkDown viewer/editor. On Mac, I recommend Typora.
2. Install a recent Python version.
3. Install pip and setuptools if needed. Recent Python versions don't need this step.
4. pip install openscad_docsgen
5. Clone the GitHub BOSL2 repo locally, if you haven't already. git clone https://github.com/BelfrySCAD/BOSL2.git
6. cd BOSL2
7. Clone the GitHub BOSL2.wiki repo locally. git clone https://github.com/BelfrySCAD/BOSL2.wiki.git
8. cd BOSL2.wiki
9. rm -rf images *.scad.md
10. Run docs generation in the BOSL2 directory: openscad-docsgen
11. Wait half an hour or more.
12. Run tutorial generation in the BOSL2 directory: openscad-mdimggen
13. Open BOSL2.wiki/Home.md with your MarkDown viewer/editor.

[pfelecan]

Thank you for these procedures.
I followed the second one.
There are just 3 issues:

1. In the mkdocspdf.sh script, the PANDOC environment variable gives the path of pandoc which is probably what you have on your system, i.e., /usr/local/Cellar/pandoc/3.1/bin/pandoc, which can be replaced by the true pandoc path or just the command name.
2. In the same script, the --embed-resources for pandoc is not supported before the 2.19 version; it can be omitted.
3. The more serious one is that the images are not generate by the openscad-mdimggen command, i.e., the directories in BOSL2/BOSL2.wiki/images/ are empty.

Anyhow, the process is almost there with the exception of the images generation.

As a note, for those using GNU/Linux Debian trixie, the testing branch, use pipx instead of pip to install the pyton packages needed for this operation in a virtual environment.

[revarbat]

I have just generated a 2138 page 64MB hyperlinked PDF file of all the docs, but it's too big to attach to this Issue.
To generate it, you need to install pandoc, and run the ./scripts/mkdocspdf.sh script after generating or downloading the BOSL2.wiki docs as shown above. Then you need to open the 160MB BOSL2_Docs.html file, and print the result to PDF. I've had success doing this using Safari on the Mac.

[pfelecan]

I've done the same thing but have a lesser number of pages - well, maybe a question of page size.
The annoying thing is that the references, i.e., hyperlinks, make reference to the HTML document, not to the internal PDF links - but maybe that is a converter issue, in my case Firefox.

I tried to generate the PDF file using pandoc but the images are not embedded.

BTW, Chrome cannot load the document, at least on my GNU/Linux Debian system.