RTD is the new DOC (maybe ;-)

[Nico Zanferrari]

Hi everybody,

long story short: take a look here https://nicozanf.github.io/py4web-doc !

INTRO: 

• MarkMin / MarkDown is simply not suitable for advanced documentation and is not at all a standard (here are some good thoughts)
• we waste time in order to make applications for displaying the output, with varying degrees of success
• obtaining the pdf is cumbersome (and is always dated), and the epub is missing
• the docs on GitHub is not necessary the same you can see on the Web site (a manual synchronization must be done)
• we cannot have the documentation for different releases
• translations are made manually without the usual tools (gettext and .po files) 

PROPOSAL:

• use RST files (even if I know they're not simple nor perfect), and produce ReadTheDocs output. Host them directly on GitHub pages. 

NERD DETAILS:

• I've written a program for converting the official MarkMin documentation to 'standard' MarkDown files (a lot of work with regex magic...). Then I've shrunk them with Pandoc (https://pandoc.org/) to obtain the RST files.
• Finally I've followed the excellent work of Michael Altfield in order to have HTML, PDF and EPUB automagically published and updated on GitHub pages, along with .po files for translations.  At every change in the repository, GitHub Actions kick in and take care of generating the new version of all the outputs in few minutes

RESULT:

• at https://nicozanf.github.io/py4web-doc you have the result. Note that we already have multiple versions (master and dev) and languages (but I've only copied the first two lines of the existing PT version). PDF and EPUB files are also ready to be downloaded.

WHAT IS MISSING

• all the internal links in the documentation are now missing. They should be checked manually (they are not so much, and mostly wrongly copied from web2py)
• translations are not tested for problems during updates
• few formatting problems with long lines on program's listing

What do you think? Is it a valuable improvement or not?

Cheers,

Nico

[Tom Campbell]

Fantastic work. Although I love markmin adopting this would speed my writing and it obviously creates excellent output. The main reason is that GitHub previews Markdown with formatting intact. My life is pulverized into tiny fragments of time. It helps me massively to be able to just jump in and make changes (or even write whole chapters) using the web interface without having to install anything.

[Nico Zanferrari]

Thank you, Tom. By the way, there are also RST extensions for VS code if you use it.

I've just added mm-converter.py , which is the simple program I've created for converting MarkMin files to MarkDown (+ RST & HTML, using Pandoc). It took weeks to learn the regex magic needed, but now it runs quite fine.

I've also made a simple test for the translations: it seems OK (new english strings are inserted in the translated ones without loosing the work already done).

 

Last but not least, I've added an optional Dark theme and the 'maybe-too-early-to-define-official' py4web logo ;-)

Nico

--
You received this message because you are subscribed to the Google Groups "py4web" group.
To unsubscribe from this group and stop receiving emails from it, send an email to py4web+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/py4web/624df331-feb8-476e-a886-cd420a4266b9o%40googlegroups.com.

[Massimo]

OK. I am sold. This is fantastic. Let's make it the new official documentation. we can discuss Saturday.

[Villas]

Holy smoke,  the docs look brilliant.  Plus MM converter!

Thanks so much! 

[Danel Segarra]

Nice!!!

[Jim Steil]

Nico

Massimo just merged my grid documentation updates.  How big of a job is it to pull them in?

-Jim

[Nico Zanferrari]

Just 5 minutes, don't worry ;-)

My proposal seems well accepted (thank you all). We'll see in the chat later how much time does it take to set it up on the official GitHub - if it's too much I could pull it in advance.

Nico

To view this discussion on the web visit https://groups.google.com/d/msgid/py4web/21af4d8d-f3b0-48ae-b525-3d88b1513f2eo%40googlegroups.com.

[Nico Zanferrari]

Docs updated on   https://nicozanf.github.io/py4web-doc ;-)

Nico

[Jacinto Parga]

Nico,

I like very much the interface to read the docs. It is clear and easy to read. 👍🏻👏🏻