User manual: Document user-callback scripts for users (migrate to MkDocs)

[buhtz]

Introduction

Welcome to the project, if you pick up this Issue because of the "GOOD FIRST USE" label. You will be mentored through the process if you want. First the Issue is explained. At the end you will find some guidance for first contributors. Please do not hesitate to ask questions. Your solution don't need to be perfect.

Problem

Back In Time (BIT) offers a feature often refereed to as "user-callback". Users can install their own scripts that will be called by BIT while a backup process is done.

The documentation of that feature is not centralized in the user manual and not easy to access for regular users.

Solution

Join the existing documentation into one place/document. Improve that document by help users to easier understand the feature, e.g. via examples.

The "place" or "document" can be a simple text document or a new piece into our own documentation system. This is up to you and depends on your skills and wishes. If you want you can offer a solution for an alternative manual-generating system. E.g. I am quit interested into docusaurus, MkDocs or mdBook. Currently the project do use Sphinx but we don't have to stick with it. We are open to discuss alternatives. In the end the content of the document itself counts. It is easy to integrate it into several documentation systems.

Resources

• There is the separate repository bit-team/user-callback explaining details in its README.md and also offering example scripts. This is a good start.
• In the current repository (bit-team/backintime) see the file common/plugins/usercallbackplugin.py.
• The project offers a source code documentation. e.g. about usercallbackplugin.py.
• We have a user manual (generated via Sphinx) which is outdated and (to my knowledge) do not contain information about the "user-callback" feature.

Your next steps

1. Please introduce your self and tell us about your skills, wishes and plans.
2. Before investing to much work into something please discuss your approach or plan with us.
3. Read the existing contributors documentation.
4. We can develop the next steps in the further discussion.

We looking forward to work with you.

[stcksmsh]

Hello,

I'm a third-year software engineering student, still pretty green but eager to learn and contribute. My experience mostly revolves around small personal projects (a simple android app and a chrome extension for instance), so this is a bit of a leap for me into the world of open source software.

I've taken the initiative to create a Markdown file to consolidate the scattered information about the "user-callback" feature, for now this is simply to have it all in one place. Currently, I'm exploring Material for MkDocs as a potential documentation generating system. However, I'm open to discussing alternative approaches and incorporating feedback from the team.

I'm looking forward to collaborating with the team and contributing to improving the project's documentation.

Cheers,
stcksmsh

[buhtz]

Dear Kosta,
welcome to the project. We appreciate your efforts. Please don't hesitate to ask if you need more information or help.

The decision about the documentation system will be done in the team. To have better ground for discussions it would be great if we could see a MkDocs setup as a prototyp. The user-callback topic is a good first content for such an MkDocs generated docu. You can describe how to setup and run MkDocs on our local machines and/or you can try to setup a project at readthedocs.org as a live demonstrator.

Based on that prototyp it will be easier for us to discuss and decide.

I don't know if MkDocs is easier to setup then Sphinx for example. But what I really like is 1) that MkDocs has a relatively clearly defined purpose and 2) that it is written in Python.

Currently some team mates are in holiday mode. So there is no hurry.

If you don't like to experiment with MkDocs or something else you are free to just update the existing Sphinx based documentation with your user callback content.

Best,
Christian

PS: When you are located in Montenegro what are your native or secondary languages? Maybe you want to have a look at our translation platform. BIT's translation into Serbian (41%), Bosnian (18%) and Croation (20%) need some love. And some other languages, too. 🌏

[stcksmsh]

Hi Christian,

Thanks for the welcome and instructions. I'll set up a MkDocs prototype for the user callback topic. I'll provide clear instructions for setup and explore readthedocs.org for a live demo.

I'll keep you posted on my progress. Also, I'll check out the translation platform and contribute to Serbian, Bosnian, and Croatian.

Cheers,
Kosta

[stcksmsh]

Hello,

I've created an mkdocs project and hosted it on readthedocs. You can access it here.

I want to apologize for the delay in completing this project. Due to a heavy workload at university, it took me longer than expected.

I've also developed the user-callback documentation, available here. I hope this meets your expectations, at least for now.

Thank you for your patience.

Best regards,
Kosta

[buhtz]

Dear Kosta,
thanks a lot for this contribution. Looks great to me. Is this the repo that doc is build from? How would you build that docs on your local machine?

I assume it will take some weeks to discuss your great prototypes with the other team mates because some of them are on holiday.

So please be patience. We have to wait a bit.

Best,
Christian

[stcksmsh]

Sorry for the late reply,

Yes, that is the repository from which the documentation is built. I utilized this script to convert the existing documentation from Sphinx's rst format to a suitable Markdown format for MkDocs. Subsequently, I addressed minor issues that persisted in the newly generated files. Additionally, I included some new screenshots, along with screenshots featuring the dark theme for the documentation in dark mode.

To build the documentation, you'll first need to install the necessary pip modules into the Python virtual environment. You can find the required modules listed in the requirements.txt file within the repository. After installation, simply execute mkdocs serve for a live preview or mkdocs build to generate the complete documentation.

Regarding the outdated documentation, I'm willing to undertake a thorough review and update of the entire content, possibly even restructuring it completely. Rest assured, the current version will remain accessible throughout this process.

Furthermore, I'm currently working on a MkDocs version of the 'dev' documentation and will keep you informed of its progress.

Please feel free to share any suggestions, questions, or requests you may have. Given that this is not my project, your input would be invaluable in determining the best course of action.

Looking forward to your feedback!

[buhtz]

Just a short question: There are ~50 packages in the requirements.txt. How do you figured them out? Are you sure that mkdocs need all of them in this setup?

[stcksmsh]

Sorry about that, some packages have been left unused, I have cleaned up the requirements.txt now. There are still some packages that are not used right now (like mkdocstrings) but will be used soon (in the case of mkdocstrings for the dev documentation). Do you have any guidelines on what I should do next?

[buhtz]

There are still some packages that are not used right now (like mkdocstrings) but will be used soon (in the case of mkdocstrings for the dev documentation). Do you have any guidelines on what I should do next?

In this case I would suggest to comment out that packages and also add a comment on top of them to indicate why this comments are there and for what they are used. The same for used packages. What are they used for? Or just a link to their project site. This lower the burden for future maintainers.

Sorry

No need for so much "sorry" and "apologize". 😄 We really appreciate your work, your ideas and contributions. 🤟

Do you have any guidelines on what I should do next?

No known to me guidelines. It can take some weeks until we can come to a decision about the docu system. We are a team on 3-4 people trying to decide such things on consensus. A docu systems has a big inpact on the future of the project and on its maintaining workflow.

I suggest currently not to invest resources in modifying the content of the documentation. Leave it as it is and wait for the discussion and decision. I can not guarantee that we might roll everything back to Sphinx.

[buhtz]

I vote for MkDocs.

In the following I will try to summarize my opinion and arguments as short as possible. 😆 I lack solid evidence. My perspective mainly relies on intuition and unlucky experiences with Sphinx.

• I differentiate between documentation for users (manual) and for developers (code reference). This issue here is about manuals. But maybe someone will come up with the point that Sphinx is able to do both. I would like to preemptively disagree with that. Despite what tutorials and its users are saying Sphinx was never able to do a full-automatic code documentation. I really tried it in the past multiple times. Even the autodoc-extention is not able to do that. A py-file alone won't work. You always have to give a rst-file (like a structure template) to Sphinx to make it work. There is a misunderstanding abou the term "automatic" between the Sphinx-community and the rest of the universe. The behavior can be named semi-automatic. Real automatic code-docu tools are Doxygen or Pydoctor. But this will be a separate issue.
• Mkdocs is simple because its features are focused on the one task to create user documentation.
• Mkdocs is younger and doesn't carry many legacy burdens (Altlasten).
• Comparing the amount of necessary configuration and its complexity I don't see significant differences between Sphinx and MkDocs.
• MkDocs use markdown. We use the same syntax in our repository for several other documentation files. That promotes uniformity and reduces burden in maintenance.
• Compared to ReStructuredTest used by Sphinx using markdown also lower the obstacles for new contributors.

As you see there are not much killer arguments on my side. 🍰

Reflecting my own workflow I often see Documentation issues. But I don't touch them. It is like "taking out the trash". But I also hesitate because I have to touch rst-files and fingering around with the Sphinx config. Just for myself the obstacle to touch the Documentation issues would be much lower having a more simpler and Markdown based documentation tool.

My hope is that switching to MkDocs will bring some more activity into the documentation issues.

Looking into the future I see no hard or bad consequences switching to MkDocs. It won't hurt.

[buhtz]

Dear Kosta,
thanks again for your efforts. Because there are no new arguments on this matter I would say we can give MkDocs a try.

Based on your example repo I will do the first step and migrate the user manual to MkDocs.
After I am finished with that you can integrate the user-callback docu into the user manual in a separate PR.

Christian

EDIT: 🚀 🎆 🌷 😮 Awesome! Mkdocs starts a local webserver and while editing the config file the webserve auto-updates its visual. Live configuration...!