DOC: Moving away from restructured text

[funilrys]

For a long time, I adopted the reStructured Text format for the documentation and READMEs. I now believe it has been an error and we should fix that.

I also believe that a mkdocs formatted documentation is more appealing for everyone: End-Users, Contributors, and Developers. Therefore, I started a new branch named switch-to-mkdocs which we should use for the documentation - until it gets merged into the dev branch.

If you want to see, what it looks like - right now, feel free to execute the following:

git checkout switch-to-mkdocs
pip3 install --user -r requirements.docs.txt
mkdocs serve

You are free and welcome to comment on this issue with:

• everything that you think is missing
• everything that you think should be rewritten or deleted

from the READMEs or documentation.

Cheers!

[funilrys]

• [ ] https://github.com/funilrys/PyFunceble/issues/265 should be fixed.
• [ ] https://github.com/funilrys/PyFunceble/issues/329 should be fixed.

[spirillen]

Why not just use the gh wiki?? it is the same structure and you only need to transform month of my works once!

[funilrys]

It's also a syntax conversion a lot of things won't change.

I also want the documentation to be a bit more "modern" looking. Right now, we can't embed any example asciinema videos ... 😞

See by yourself how it looks now:

git checkout switch-to-mkdocs
# activate environemt
virtualenv -p python3 venv
. venv/bin/activate
pip install -e .[full]
# Serve documentation locally.
mkdocs serve
# Open Documentation with browser.
palemoon http://127.0.0.1:8000

[spirillen]

Not spend a lot on this one, but ran into this error

mkdocs serve
Error: MkDocs encountered an error parsing the configuration file: while constructing a Python object
cannot find module 'material.extensions.emoji' (No module named 'material.extensions')
in "$SOME_PATH/funilrys/pyfunceble/mkdocs.yml", line 48, column 20

[funilrys]

Nice catch. I really need to start testing everything inside a container ...

[funilrys]

Patch is on its way.

[spirillen]

A short first hand impression... :unamused: The white background is a killer. I would also recommend using a background color in the banner of the same green as your logo.

Browsing structure... not worse, but images are not loaded as you might have expected

---

These are only first hand impression, and I will spend some time reviewing the code in competition of JetBrains witerside, Yet another markdown tool that allows you to do a lot of cool stuff(config) and controlling the behavior. (Free tool), this again in competition to the YouTrack(paid version, but no diff to free version) knowledge base, which includes a issue board that can interact with Github/Gitlab issues. And a helpdesk Requires login, but the submitform is HTML based and is designed to be included in any other html based page.

The preview should be available at https://kb.mypdns.org/articles/PF-A-1/PyFunceble (Once the accessibility have been solved by JetBrains support)

[spirillen]

@funilrys You can download https://github.com/spirillen/PyFunceble/tree/spirillen-writerside-v.0.1a and have a preview for the docs written with the writerside tool, the page I have been playing the most with is lookup.html where you can see examples of features I'm not aware of should be available to mkdocs.

Next I will fill the gh wiki for comparison https://github.com/spirillen/PyFunceble/wiki

Please let me know what you choose as I might be open for helping transferring the docs into new format

UPDATE: Dropped the WIKI, it just sucks...