Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Moving away from restructured text #340

Open
funilrys opened this issue May 27, 2023 · 8 comments · May be fixed by #347
Open

DOC: Moving away from restructured text #340

funilrys opened this issue May 27, 2023 · 8 comments · May be fixed by #347

Comments

@funilrys
Copy link
Owner

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 funilrys self-assigned this May 27, 2023
@funilrys
Copy link
Owner Author

funilrys commented May 27, 2023

@spirillen
Copy link
Contributor

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

@funilrys
Copy link
Owner Author

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
Copy link
Contributor

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
Copy link
Owner Author

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

@funilrys
Copy link
Owner Author

Patch is on its way.

funilrys added a commit that referenced this issue Dec 20, 2023
This patch fixes #340 (comment).

Contributors:
  * @spirillen
@spirillen
Copy link
Contributor

A short first hand impression... 😒 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

image


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
Copy link
Contributor

spirillen commented Dec 25, 2023

@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...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: In progress
Development

Successfully merging a pull request may close this issue.

2 participants