On 9/8/22 6:00 PM, Andrew David Wong wrote: > On 9/7/22 6:30 PM, mm wrote: >> [...] >>>>> 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.) >
Ah, I already see one side effect of moving these pages to the main repo: They can no longer appear in the doc index, probably because the script that populates the doc index only checks for files in qubes-doc, which is probably one of the reasons we had them there in the first place.... -- 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/d7a89487-2aa3-466d-a179-0e1968b22f37%40qubes-os.org.
