Proposal (RfC): New Github repo for technical documentation?
I am just diving deeper into Wayland and would like to create and publish a kind of summary doc as markdown file for us. Do we already have a Github repo for this kind of technical/development documentation? The "doc" repo seems to contain the end user documentation and I wouldn't put dev docs in there. I propose to add a new repo called "tech_docs" (or "dev-docs")... Any ideas/wishes/objections/proposals? PS: The generated API doc (via Sphinx) could also be published in the new repo regularly (eg. for each release). The API doc sources are stored in the common/doc-dev folder in Github (but not the generated API doc itself!).
Dear Jürgen, dear Folks, Am 02.11.2022 01:58 schrieb BiT dev:
I am just diving deeper into Wayland
Glad about that because I understand nothing about it. ;)
and would like to create and publish a kind of summary doc as markdown file for us.
Very good.
Do we already have a Github repo for this kind of technical/development documentation?
I also think we don't have this.
The "doc" repo seems to contain the end user documentation and I wouldn't put dev docs in there.
Agree. The user docu is another interesting topic.
I propose to add a new repo called "tech_docs" (or "dev-docs")... Any ideas/wishes/objections/proposals?
PS: The generated API doc (via Sphinx) could also be published in the new repo regularly (eg. for each release).
About the API doc: I don't see a need to publish the generated API doc because BIT isn't a reusable library with an API like pandas, qt, gtk, etc. Every developer should generate the HTML locally when it is needed. I don't see an advantage or a need in publishing the API docs. About a tech_doc repo. I'm tend more into the centralized direction. As discussed earlier somewhere else (sorry can't remember the link) I also would re-join the "doc" and "user-callback" repo back into "backintime". Keep it all in the same place. Not now but someday. I don't see a disadvantage of keeping the tech-docu in the main repo. As example you still created the nice "common/doc-ev/1_doc_maintenance_howto.txt" file. I would keep that approach of having such files and link them together. You can also semi-auto-generate TOC intries for such files using tools like https://derlin.github.io/bitdowntoc/ or something else. By the way: The "1_doc_maintenance_howto.txt" file seems to be a reStructuredText file and should have ".rst" as file suffix then. If we keep the tech_doc in the main repo we should discuss some of that points and find consensus in the team 1. Doc file syntax: reStructuredText (e.g.[1]), Markdown (e.g. [2]) or something else. 2. Organizing the files. Folder structure. Nameing conventions. Or maybe just keep one big tech-doc-file. 3. Link them together. e.g. a tech-doc-landing-file linking to all other files. To 1: I vote for Markdown most just because of my personal taste and everyday work. But also of its simplicity, more widespread use and easier access for new contributors. To 2: I vote for keeping one big tech-doc-file in the first place and keep track of its content via a (semi-auto-generated) table of content on top. Then we can see where the journey goes and how big it becomes. To 3: Mentioning the file in README, CONTRIB (we don't have that yet) and FAQ file. Another thought: Maybe someone would mind about write the tech-doc into the sphinx files. But I won't go with that. Every time you write something into the Sphinx files you have to generate the HTML to see if evrything is fine or you did something wrong. IMHO very annoying. I strongly prefer one of the plain text based formates like Markdown or reStructuredText. [1] -- <https://github.com/bit-team/backintime/blob/master/common/doc-dev/1_doc_main...> [2] -- <https://raw.githubusercontent.com/bit-team/backintime/master/README.md>
I think it's a good idea to keep a dev documentation. Especially for us, a new team understanding the existing code, it would be useful. So we recognize the need ;) I agree with Christian that another repo would add overhead, but not much benefit. We would have a separate set of Issues, permissions and commit history to deal with. In an ideal world, we would find a solution to sensibly order and integrate all documentation that currently exists, which to my knowledge is: - the https://github.com/bit-team/doc repo (source for the docs published at https://backintime.readthedocs.io ) - the GitHub Wiki/FAQ - random bits if information in README.md - code documentation (Sphinx? etc.) - the newly proposed API/dev documentation Not sure about the best way to do it! Michael
THX Christian and Michael for your feed-back. I will add a new folder "doc-dev" to our existing repo https://github.com/bit-team/backintime which is consistent to the existing "doc-dev" name under "common". I will add markdown files there for new documentations, currently (until this weekend) only one single file: - "Background about Wayland vs. X11 with Qt5" as a quick introduction into the topics without the need to read the overwhelming external documentation I also will add (manually for now) a central doc-dev index markdown file into doc-dev to provide a quick overview over all existing documentations that we have and will create in the future. Reasons for using the same repo: - no overhead, no separate issues, no separate permission handling - documentation matches the source code (supports tagging and branching) Reason for using markdown: - It will be rendered automatically by Github (reStructuredText is a beast without rendering support at GH I think) As Christian wrote I will NOT put the generated API doc into "doc-dev" since it can be generated.
[Christian:] Maybe someone would mind about write the tech-doc into the sphinx files. But I won't go with that.
I agree. I do use Sphinx only to generate our internal API doc from the Python docstrings (no additional text in rst files). Please veto if I should change something (folder name etc.)...
About the API doc: I don't see a need to publish the generated API doc because BIT isn't a reusable library with an API
The Sphinx API doc is already published at https://backintime.readthedocs.io/projects/backintime-dev/en/latest/ but it is definitely out-dated and I don't know the workflow to update this. Who understands this workflow? Or shall we remove this old published API doc again?
[Christian:] By the way: The "1_doc_maintenance_howto.txt" file seems to be a reStructuredText file and should have ".rst" as file suffix then.
It is plain text (no need to render it to make it readable :-) On Wed, 2022-11-02 at 10:53 +0100, Michael Büker wrote:
I think it's a good idea to keep a dev documentation. Especially for us, a new team understanding the existing code, it would be useful. So we recognize the need ;)
I agree with Christian that another repo would add overhead, but not much benefit. We would have a separate set of Issues, permissions and commit history to deal with.
In an ideal world, we would find a solution to sensibly order and integrate all documentation that currently exists, which to my knowledge is: - the https://github.com/bit-team/doc repo (source for the docs published at https://backintime.readthedocs.io ) - the GitHub Wiki/FAQ - random bits if information in README.md - code documentation (Sphinx? etc.) - the newly proposed API/dev documentation
Not sure about the best way to do it!
Michael _______________________________________________ Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: python@altfeld-im.de
Moin Folks, Am 03.11.2022 00:35 schrieb BiT dev:
I also will add (manually for now) a central doc-dev index markdown file into doc-dev to provide a quick overview over all existing documentations that we have and will create in the future.
I can try to provide kind of a collect-headings-and-generate-toc-script.
Please veto if I should change something (folder name etc.)...
Sounds nice to me.
The Sphinx API doc is already published at https://backintime.readthedocs.io/projects/backintime-dev/en/latest/ but it is definitely out-dated and I don't know the workflow to update this.
Interesting. I didn't noticed that we have two readthedocs entities; one with the API and one with the "user manual". I never regulary worked with readthedocs but I tried once. It work that way that it runs it's own Sphinx instance on the server. To do that it clones the given GitHub repo first. So the repo need be setup the right way that the readthedocs server can run Sphinx. Maybe there are errors currently and that is why the doc isn't updated. Or the "automatic" (each PR/comit or something else) isn't activated. I tried my old account which is connected to my GitHub account. Because I'm now bit-team admin I can see all three BIT repos on readthedocs, too. I suspect you can do the same. But I can't access Germars original readthedocs setup. So I stoped to prevent us from having a duplicated readthedocs entity for BIT. We should add this on the ask-Germar-question-list.
Or shall we remove this old published API doc again?
Maybe we can handle that later. But if you ask me I would say we could remove booth readthedocs entries; the API doc and the user manual. BIT doesn't have to be complicated from a users perspective. I'm an utopist about GUIs: A good GUI does explain itself and the user never need to read a manual to know how to use the application. But of course we need to redesign the current GUI to come closer to that goal. In the current state where the manual only shows and describes all GUI dialogs and its buttons I don't see much value in it. I would prefer a more use case orientated or tutorial like help text: How to use an external USB drive? How to backup on NTFS? How to backup as root? etc etc And to reduce the complexity of our repo and its setup this can be realized with simple markdown files. We don't need Sphinx for that. Using Sphinx for user manuals or (simple and for internal) API docs is like using a Spaceshuttle just to buy some buns from the bakery around the corner. ;) It works it looks awesome but took a lot of resources. Sphinx is a nice piece of software with a specialized usage area which is today often misused far away from that area it was build for. Sphinx is my topic... :D But to be objective and orientated on the current state of the project and its needs. Keep the user manual and remove the API doc from readthedocs. Kind Christian
On Thu, 2022-11-03 at 10:58 +0000, c.buhtz@posteo.jp wrote:
But I can't access Germars original readthedocs setup. So I stoped to prevent us from having a duplicated readthedocs entity for BIT.
What exactly do you mean with "stopped to prevent us"?
We should add this on the ask-Germar-question-list.
Definitely
But if you ask me I would say we could remove booth readthedocs entries; the API doc and the user manual.
I'd also drop the API doc there but would prefer to keep the user manual (even if outdated currently) until we migrate it back to github. Reason: In issues in sometimes refer to GUI dialogs and its documentation and I need a public URL for that.
I would prefer a more use case orientated or tutorial
This is a big gap so far (except perhaps some covered topics in the FAQ/wiki)
Keep the user manual and remove the API doc from readthedocs.
I fully agree. Who can do this (except perhaps Germar)?
participants (3)
-
BiT dev -
c.buhtz＠posteo.jp -
Michael Büker