stdlib-js / www

Website for stdlib, a standard library for JavaScript and Node.js.

https://stdlib.io

Apache License 2.0

6 stars 8 forks source link

[RFC]: add support for exporting API docs to a PDF #30

Open kgryte opened 2 years ago

kgryte commented 2 years ago

Description

This RFC proposes adding support for exporting API docs to a PDF.

PDF documentation could be useful outside of the website and in the context of offline usage. PDF docs are common in, e.g., R and TeX documentation.

Generation of the PDF could be done either on-demand (client side; see htm2pdf.js) or pre-compiled on the server and simply sent on request.

HTML to PDF can be problematic, as a common technique is to capture HTML as an image, which prevents the generated PDF text from being searchable or selectable.

This RFC would benefit from gh-27, where JSON could be used to automatically generate TeX which could then be compiled to a PDF.

Related Issues

Related issues #27.

Questions

No.

Other

No.

Checklist

[X] I have read and understood the Code of Conduct.
[X] Searched for existing issues and pull requests.
[X] The issue name begins with RFC:.

Planeshifter commented 2 years ago

Alternatively, could use pdfmake in combination with html-to-pdfmake, which I have been using with some success.

kgryte commented 2 years ago

Yeah, my sense is that anything HTML-to-PDF will be tricky/imperfect given our heavy reliance on CSS, and that a more robust conversion pipeline over the long term would be JSON-to-TeX.

Planeshifter commented 2 years ago

While not getting us near the ability to export the entire docs as a PDF document, I tweaked our CSS a bit per https://github.com/stdlib-js/www/commit/8eec861b0fce7171b814d9132474c3838679879c to allow one to nicely print the current README.md from the docs website without any interface elements.

Planeshifter commented 2 years ago

Here is an example:

array_shape_readme.pdf

We could consider having additional elements that are only visible when printing, e.g. some attribution / date of export. What do you think?

Planeshifter commented 2 years ago

Also a added a button to print the currently selected README.md per a9495a12bc6b96f12a1a5f9536cebe695b20aba2.

Dark theme:

Light theme:

kgryte commented 2 years ago

Yeah, adding a copyright notice might be one thing to add, along with the date of export.

Planeshifter commented 2 years ago

And maybe the version of the docs for which the README.md was exported...

kgryte commented 2 years ago

Yeah, that makes sense, as well.