On 9/8/22 6:15 PM, Andrew David Wong wrote: > On 9/8/22 6:14 PM, Andrew David Wong wrote: >> 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.... > > But maybe that's okay, since once we migrate to RtD, we'll no longer be > relying on custom scripts like this to populate the table of contents. :)
Well, I guess I better move back at least the Downloads and HCL pages, since having those in the index is pretty important. I guess the others can stay in the main repo, since they're linked from the Security Center page. -- 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/b78f4cc0-f38d-1445-ca01-d38a965be3e7%40qubes-os.org.
