On 9/7/22 6:30 PM, mm wrote: > [...] >>>> https://github.com/maiska/qubes-doc.rtd/commit/0b8529a026da0523355eec55c57c1da2aa110d07
By the way, with this one, the link is not actually broken. It still works, because your browser adds the missing forward slash automatically. Nonetheless, I've committed a fix to make it technically syntactically correct. > [...] > other people's articles linking to the official Qubes OS documentation would > be broken, since I do not think that there is a proxy > > to handle such requests and redirects? Or there is a simpler way? > I don't understand why links would get broken. Let's use a concrete example to help me understand. Take this page, for example: https://www.qubes-os.org/doc/how-to-update/ After the migration to RtD, wouldn't this still be the same URL for that page? Why would it be any different? If you're saying it has to be a different URL for some reason, what would the new URL look like? >> Wouldn't converting all Markdown files to RST result in still using the _doc >> submodule, just with all the files converted? Maybe I'm not understanding >> something here. > > This could be a possibility yes, perhaps with a sphinx plugin for redirects. > It exists, haven't tried it yet. > Why only "a possibility"? I figured that would be the obvious thing to do, but clearly I am missing something. If there is a good reason to do otherwise, then that's totally fine! It's just not clear to me what that reason might be. > [...] >>>> 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... >>> >> I think this goes back to the previous discussions we've had over the years >> about how to organize website vs. doc content, and we landed on organizing >> it this way for various reasons. I think one of those reasons was to have >> everything that should be included in offline documentation in qubes-doc. >> (So, even if the data is in `_data/`, the offline doc generation tool might >> decide whether to include it based on whether the page referencing that data >> is in qubes-doc or not.) >> >> Also, it might be a bit weird to have a page (/security/) in qubes-doc, >> while its "subpages" are in the more general parent repo "above" it. So, >> organizing based on semantic content vs. source file/data attributes will >> get you different results. >> >> I'm sure there are many other considerations buried in our archives that I'm >> forgetting now. > > From my part what I see is more work. It dragged itself through the years > enough :) (Of course that is also on me) > > As soon as we get the localization workflow going and RTD is the way to go as > discussed previously and is stable, > > one can still play with sphinx templating and incorporate the above files in > the RST documentation. I already tried it as a simple example it functions, > but is frustrating, and rn I do not have the nerve to sit through this. > > Perhaps some volunteers will come forward at the summit :) > Ok, if it's too much trouble to get the tech working correctly, then that's probably a good enough reason to just move these files. I don't mind. > Why I see them as a part of the website is the following: downloads, xsa, > qsb, canary and pgp-keys are somewhat essential to security of the project, > not truly documentation as I see it atm > Well, I don't know if that holds for all of these, because at least some parts of those pages are clearly documentation explaining what XSAs are, what QSBs are, what canaries are, how we handle them, and so on. But the other technical reason you gave enough is a separate and probably good enough on its own. Ok, I've just moved these pages to the main repo and deleted the ones we don't need. > HCL is documentation yes, there I just make my life easier > Yes, making life easier is probably more important at this stage. :) (Btw, I'm assuming you meant *not* documentation, since above you listed the HCL page as one that you said *should* be moved to the main repo, which makes sense because it is indeed "empty" with all the data stored elsewhere. So, I've just moved it along with the others.) >> >>>> 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. >>> >> Well, most of these are intentionally not linked from the main index for a >> reason. >> >> Qubes builder -- probably a subpage linked from a main page >> Join -- intentionally hidden when active recruiting stopped (to be unhidden >> if/when it resumes) >> Admin API Table -- it's an "embed" on the Admin API page (just a hack to >> allow opening that huge table by itself in the "fullscreen" layout) >> Disposable VM Implementation -- not sure >> Qrexec2 -- not sure >> Qfileexchgd -- not sure >> Code of Conduct -- linked from footer, as Marek said; would be okay to link >> from index >> Intro -- linked from "nav bar" at the very top of the website >> Privacy -- intentional footer link, like every other website >> Screenshots -- linked from Intro; would be okay to link from index >> Statistics -- linked from News page; would be okay to link from index >> Video Tours -- linked from Intro; would be okay to link from index >> QSB Checklist -- checklist for internal use; probably not of interest to >> users; would just be clutter in the index >> Canary Checklist -- same >> Download mirrors -- table embedded on Downloads page >> Custom install -- linked from Installation Guide; would be okay to link from >> index >> Install security -- linked from Installation Guide; would be okay to link >> from index >> How to use the hcl -- linked from HCL page; would be okay to link from index >> How to reinstall a template -- subpage linked from Templates page >> Debian template -- this page is already linked from the index; not sure why >> it was miscategorized as a hidden gem >> Debian upgrade -- in-plage upgrade guide subpage linked from Debian page >> Fedora upgrade -- in-plage upgrade guide subpage linked from Fedora page >> Fedora -- this page is already linked from the index; not sure why it was >> miscategorized as a hidden gem >> Update Debian Whonix -- looks like this got missed in the contributor >> overhaul of troubleshooting documentation that occurred a while back; it >> might just be outdated now >> >> IMO: >> >> - If a page exists purely as a technical workaround (hack), then it makes >> little sense to list it in the index. Pages that exist purely to serve as >> embeds in other pages probably fall under this. The content is already >> presented somewhere in a rational way, and this just creates a confusing >> duplicate pointer to part of it without its intended context. >> >> - Internal docs like maintainer checklists would probably just be >> confusing/useless for readers, but I suppose it's okay to list them if you >> want. (If we don't really use these, then we can just remove them.) >> >> - In a few places, a subpage only exists because people thought that >> including its content "in-line" in its parent page would make the resulting >> page "too long." I guess it's okay to list these, but it might help to at >> least update the titles to make the parent/child relationship clear. > > Yep, some of the gems are referenced from the footer for example. > > Why I brought them to light in the index for discussion is the weird feeling > getting to qubes os documentation on RTD and not having all the files at > one's click. > Well, I think I explained above why that should not be a weird feeling. That's a bit like saying, "I bought a house, but it's a bit weird that I can't easily see and touch the insides of my own walls." o_O > As part of the official Qubes OS website it made sense and I did not really > notice. > > RTD is different story. > > I think if RTD should host them, the reader should be able to find them from > the index somehow, or a subindex whatever that may mean > Well, ok, if that makes things easier. I've now made sure all these pages are either incorporated into their parent pages (i.e., eliminated) or listed from the index. > And it is just a dump, it should be reorganized of course :) > Indeed. :) For reference, here are the two PRs where I do everything I said I did in this email: https://github.com/QubesOS/qubes-doc/pull/1267 https://github.com/QubesOS/qubesos.github.io/pull/204 -- 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/aa266dc0-14b2-9ece-90a4-f7b91e27f561%40qubes-os.org.
