Hello
We have an open bug related to creating a Debian theme for the
documentation that uses Sphinx:
#915583 debian-policy: More attractive sphinx theme, please
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=915583
Unfortunately I think nobody could put on time on this yet.
Other bugs related to Sphinx in Debian documentation that may need to be
taken into account:
#987943 www.debian.org: Developers Reference: Sphinx search
non-functional: searchindex.js missing
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=987943
#1026446
Static javascript resources for Policy and DevRef give 404 errors,
breaking search
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1026446
Kind regards,
El 19/5/23 a las 1:58, Richard Lewis escribió:
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?
--
Laura Arjona Reina
https://wiki.debian.org/LauraArjona
