-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On Sun, Sep 04, 2022 at 10:05:42PM +0200, mm wrote: > Hello Marek, > > > thank you for resurrecting the thread. I wanted to write like a week ago, > > but yet, it lasted longer. > > I am glad to announce that the initial hurdle for Qubes OS docs > RST-conversion, > localization, hosting on RtD is behind us and you can see a preliminary > result on > > https://current-qubes-docrtd.readthedocs.io/en/latest > > This is the current status of the branch rtd-test-default-html-theme in the > repo https://github.com/maiska/qubesos.github.io.rtd + submodules
This looks very promising! > To see the partially translated docs in german you can go > down to the left, click on the arrow right to 'v:latest' and choose the > language. > > There are further tweeks to be done, such as epub and pdf, but the big step > is taken (including automated conversion via script and postprocessing > cross-referencing in sphinx, but still needing minor manually fixes after > that, documentation follows) and translation workflow tested. > > I will not bother you with details at that stage but with questions. > > The outline of the questions is as follows: > > 1. Easily fixable dead end urls as found in the official docs > 2. Non easily fixable links > 3. Website content vs RtD documentation content > 4. Hidden documentation files > > 1. These are the commits that show what can be fixed imho. > > https://github.com/maiska/qubes-doc.rtd/commit/0b8529a026da0523355eec55c57c1da2aa110d07 > https://github.com/maiska/qubes-doc.rtd/commit/2b05ac2d8418adbc1d4215d3d54195b3ca8e7f58 > https://github.com/maiska/qubes-doc.rtd/commit/6772392f3e2e682d953d7e3b8d9f870867de202a > https://github.com/maiska/qubes-doc.rtd/commit/538bac0e0c368cd54e5acb0b5d1ffb77e06e5045 > https://github.com/maiska/qubes-doc.rtd/commit/eb4d1dade1697d4b9e725db8871b1c54ec8c61d6 > https://github.com/maiska/qubes-doc.rtd/commit/a8884c8e11f91458bb8ea30d6bbea49e25db48b2 > > Question: Should I just create Pull Requests for the proposed fixes Yes, makes sense. I wonder why URL checker hasn't found them... Or maybe it did but we ignored it? > 2. At least one broken for me unfixable link > > in > https://github.com/QubesOS/qubes-doc/edit/master/developer/releases/2_0/release-notes.md > l 41 > > Empty Response or No Access-Control-Allow-Origin > https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority > http://localhost:5656/developer/releases/2_0/release-notes.html > > Question: Could you fix that? :) Since that's about Qubes R2, I think the link can be simply dropped. (otherwise it's probably possible to write similar github issues filter, but I wouldn't bother) > 3. My suggestion is to keep the documentation index and some Markdown files > in the changed qubes os website repo, > the converted RST files in a new one with two submodules: attachment and > _translated Yes, this sounds like a good plan. > A new sample Qubes RST documentation repository (without any translations > yet) can be found here: > > git clone -b qubes-rst-doc https://github.com/maiska/qubes-rst-doc.git > > A new sample Qubes Website incorporating RST documenation can be found here: > > git clone -b new-master https://github.com/maiska/qubesos.github.io.rtd.git So, it references _doc submodule that basically is just about redirects to the new doc. Makes sense to keep links working. > The following files will be retained at this stage, due to liquid templating > (needs some tweeking if > one wishes to work with sphinx templating) and also these are perhaps also > just part of the official website not the documenation as I see it at least > atm > > - https://www.qubes-os.org/hcl/ > - https://www.qubes-os.org/downloads/ > - https://www.qubes-os.org/security/xsa/ > - https://www.qubes-os.org/security/qsb/ > - https://www.qubes-os.org/security/canary/ > - https://www.qubes-os.org/security/pgp-keys/ Sounds fine. IMO those should be moved to the main repo. In fact, actual data for those pages is already in the main repo (_data/), just not the .md file... > Question: Are you OK with this? Or should I leave the question for the talk? > > 4. Hidden files not yet deleted or referenced in the index are to be found > here (not in the german version of the index rn): > > https://current-qubes-docrtd.readthedocs.io/en/latest/#hidden-gems > > Question: Should the index be populated with them? You mean pages that are only linked from some sub-section but not the main index? Or not linked at all? Some of those are normally linked from the website footer, https://www.qubes-os.org/intro/ or similar. But generally, IMO better have every doc page linked to the main index. > Regarding the old translation markdown workflow - it is still there, and can > be brushed off the dust. > > P.S. I just realized that my .vimrc config was broken. Please excuse the > tabs...! - -- Best Regards, Marek Marczykowski-Górecki Invisible Things Lab -----BEGIN PGP SIGNATURE----- iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmMV47oACgkQ24/THMrX 1yw1sgf/fW9F3s/Bp1/NmqH4lBH/9jy/p49/lYs8UTU9qWWw8sJY9w6v8rVZ/N3F okWW30Pjw8j1DPx6zY9JWdvzYu9jZAABgHOLNrYY9u4O2WD9V0CFUbZNxezqDyGR rNe8XGdWrWoPDylRW7EYw4BTC6m7RPHK7h3GuyoP0YyTyxDim0+9I4vzgq304uBB NiUJLCdzRaW2x1S5ulJbgSd6iDYdiz2mGuvkaS/hbqv+OnaMkHLaOJmKaLShWY6g Z5dU2tDprpx0ohkXIfd9hTvijrDrb981qDP3pjFY2bXoFFrTaHgUn6myXFCKl5tW F728mHFxzq2LxH1XzCiFeneJ+Qg47Q== =eLlL -----END PGP SIGNATURE----- -- You received this message because you are subscribed to the Google Groups "qubes-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/YxXjuoYSGsH17fUI%40mail-itl.
