On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwans...@mailbox.org> wrote:
> I worked on this recently, and I have something like a prototype ready. > It can be found (as html) at > https://people.debian.org/~holgerw/release-notes_sphinx/ I hope the below doesn't come across as negative - it;s not meant to be: i've been submitted MRs for release-notes and found the XML syntax adds complexity to the source that mostly only results in the output using bold or fixed-width: So it would be great to simplify to rst! Unfortunately, my first impression is that it the output has quite a few issues which make it a lot harder to read than the docbook version - which im sure is because it's still only a prototype, but thought it might helpful to list the things that jumped out at me: - It is a lot more cluttered than the docbook version - it feels off-putting and dense to read - it's all a bit 'blue' - i'd suggest red is more on-brand for debian - the "next"/"prev" links at the bottom-right are white on green --- I totally missed at first, and found hard to read - i was a bit confused by the "12.1" version number at the bottom of every page, and having 'sphinx' reminded me of websites with "hosted by geocities" - are the red hyphens in eg the 'deb...' line near the top of https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html meant to be red? (maybe it is a syntax error?) - package names are no longer distinguished from other text (eg 'ntp' in https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html#changes-to-packages-that-set-the-system-clock) - the order in the contents pane on the left is a bit...unusual: it starts with the current section, then does previous, then next, so eg on chapter 2, https://people.debian.org/~holgerw/release-notes_sphinx/en/html/whats-new.html it lists chapters 2, then 1, then 3. - https://people.debian.org/~holgerw/release-notes_sphinx/en/html/genindex.html is completely blank - not sure "show source" on the left is all that useful for readers I'm sure these are easy to fix! > while the git repo containing the migration is at > https://salsa.debian.org/holgerw/release-notes Im sure i am being dumb, but i couldnt spot where the actual rst files are? - i still see eg https://salsa.debian.org/holgerw/release-notes/-/blob/master/en/issues.dbk in XML > as far as I know, sphinx/reStructuredText is still lacking some functionality, > which is heavily used in the release-notes. > That is the use of substitutions within URLs. You could always keep the entities and do a 'sed s/&oldrelease;/bookworm/g' etc before "building" with sphinx. Actually.... if i click 'show source' l get to https://people.debian.org/~holgerw/release-notes_sphinx/en/html/_sources/about.rst.txt which seems to have |RELEASE| and |RELEASENAME| rather than 12 and bookworm: perhaps sphinx supports entities after all?
