funilrys
DOC: Moving away from restructured text
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!
- [ ] https://github.com/funilrys/PyFunceble/issues/265 should be fixed.
- [ ] https://github.com/funilrys/PyFunceble/issues/329 should be fixed.
Why not just use the gh wiki?? it is the same structure and you only need to transform month of my works once!
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
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
Nice catch. I really need to start testing everything inside a container ...
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)
@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...