Write G'MIC language gmic-py Python cookbook for G'MIC beginners

[myselfhimself]

Observation: Python developers have difficulty digging into the G'MIC language. Now that gmic-py is there, an easy "glue layer" may help those users want to dig deeper into G'MIC, with appreciated help from cookbook documentation.

Related to this pixls.us discussion with @grosgood as which gmic.eu's documentation chapters are the most important for G'MIC beginners, and would make a good python-translated cookbook for Pythonists.

• [x] Create a proper branch or PR
• [x] Create a cookbook page in the gmic-py.readthedocs.org
• [x] Ensure gmic-py.readthedocs.org shows the custom branch or PR
• [x] Report each cookbook pages as empty chapters (ie. sections/anchored titles, as multi-pages documentation is complicated to do in Sphinx ReST)
• [ ] Slowly translate "pure-G'MIC" cookbook pages "G'MIC from Python" sections
• [ ] Reinstate the DISABLED_DOC/tutorials.rst file, which was moved aside for faster documentation build times

[grosgood]

Ping! Noted.

[myselfhimself]

The cookbook generates well through the github -> readthedocs hook, for the cookbook-related Pull request's branch named just cookbook. The URL for looking at a cookbook statically-rendered documentation is https://gmic-py.readthedocs.io/en/cookbook/index.html (or just gmic-py.readthedocs.io and use the screen bottom's dropdown to pick the cookbook branch).

To grab the project and point to the proper branch to edit files:

git clone https://github.com/myselfhimself/gmic-py.git # or any pure non-https, or "gh clone" method
git checkout cookbook #change to the cookbook branch

Note that if you feel lazy anyday (allowed by humanity) and like writing documentation in the blind a bit without needing any terminal work, you can use the Github's pen buttons or "edit file" links to change files in the cookbook branch, from the web browser, then wait 5-10 minutes for your changes to appear on gmic-py.readthedocs.io (cookbook variant). Example from https://github.com/myselfhimself/gmic-py/pull/92/files (see dropdown menu's "Edit file" action on the righthand corner)

To build the documentation offline (if ever it is not too complicated, otherwise I wish to simplify it for any future contributors):

mkvirtualenv cookbook -p /usr/bin/python3.7 #or python3 or no -p option at all if python3 is your default python interpreter
cd docs/ # edit cookbook.rst and/or index.rst (the table of contents and more), or any file you would like
cd .. # back to root directory
bash build_tools.bash # shows many subcommands
# full doc building, including the API introspection, may require g++/clang and gmic-py dependencies, try to skip that first: bash build_tools.bash 6_make_full_doc
bash build_tools.bash 6b_make_doc_without_c_recompilation # try this first, which spares you from recompiling gmic-py, hit Escape for each gmic windows popping up ; eventually you see a default web browser opening and showing the documentation's index.html
bash build_tools.bash 6b_make_doc_without_c_recompilation cookbook.rst # command variant where only cookbook.rst should be rerendered, to have faster docs build times
git commit docs/cookbook.rst -m "#91 some improvement"
git push origin cookbook

[myselfhimself]

@grosgood FYI readthedocs builds the cookbook branch automatically in about 360 seconds - 6 minutes: (after each push in the cookbook branch): (this UI is only for me for now, but I could share its administration to you if feel the need for more control later on)

Feel free to start by using the "Edit file" tool first, if you dislike using the terminal build environment to start with.

[myselfhimself]

tutorials.rst has been moved to /DISABLED_DOC/ so the docs build time gets ultra fast (ugly but easy technique..). Added a TODO item above to reinstate it at the end of our work.

[grosgood]

Ping! Just started writing. First post looks like maybe 12:00 EDT 16:00 UTC 4/11 thereabouts. Saw your rwcimg remark - hanging it on a to-do peg. May be pertinent for this cookbook, as a '.cimg' file is a serialized gmic image list - conceptual workalike to Python pickle.

[myselfhimself]

Hello, yes this gmic image list to cimg tutorial idea seems very relevant... Basically anything that is well packaged and adds online literature on gmic-py usage may be useful to the community... No order of delivery is important now, as most important is motivation and ability to finish someday what has been generously started. I frankly cannot predict who uses what in this project's documentation.... Some people have already written to me emails telling they use the gmic-py / numpy conversion functions although they were created on no user's request (just our intuition).