Bug#1053549: Bug#932957: New theme for docs in reStructuredText (was: Re: Bug#932957: #932957 Please migrate Release Notes to reStructuredText)
Holger Wansing wrote (Fri, 24 Nov 2023 22:49:47 +0100): > I used the alabaster theme, which is the default theme in Sphinx, and > set some configuration options in conf.py, to adapt some details. That's all. > > So no need to create a new theme IMO. > > Just set the appropriate options in the manual, and build it. I have switched trixie's release-notes to this new theme, and the result is now visible on www.debian.org/releases/trixie/release-notes. I noticed, that the links to the previous and next chapter at the top and the bottom of the pages are missing. Some research showed, that the reason for this is the sphinx version on www-master, which is a bullseye system. Starting with the sphinx version in bookworm, those links are supported. So this will start working, when wolkenstein will get updated to bookworm. Moreover, I changed the Debian logo to include the document name (here: "Release-Notes"), to have that information available on every page of the release-notes (at the top). Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#1053549: Bug#932957: New theme for docs in reStructuredText (was: Re: Bug#932957: #932957 Please migrate Release Notes to reStructuredText)
[ Re-sending message; first attempt from smartphone dropped some recipients, sorry ] Am 24. November 2023 10:50:19 MEZ schrieb Laura Arjona Reina : >I've had a quick look at the theme >inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ > and looks very nice both in my computer and my phone, and I think it's a >good improvement for the current theme. Thank you *very much*. > >I don't know which is the better way forward, maybe add a repo for the theme >in the ddp-team umbrella, and then file a bug for every documentation manual >using Sphinx, suggesting including it? I used the alabaster theme, which is the default theme in Sphinx, and set some configuration options in conf.py, to adapt some details. That's all. So no need to create a new theme IMO. Just set the appropriate options in the manual, and build it. Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: New theme for docs in reStructuredText (was: Re: Bug#932957: #932957 Please migrate Release Notes to reStructuredText)
Hi, Am 24. November 2023 10:50:19 MEZ schrieb Laura Arjona Reina : >I've had a quick look at the theme >inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ > and looks very nice both in my computer and my phone, and I think it's a >good improvement for the current theme. Thank you *very much*. > >I don't know which is the better way forward, maybe add a repo for the theme >in the ddp-team umbrella, and then file a bug for every documentation manual >using Sphinx, suggesting including it? I used the alabaster theme, which is the default theme in Sphinx, and set some configuration options in conf.py, to adapt some details. That's all. So no need to create a new theme IMO. Just set the appropriate options in the manual, and build it. Holger -- Sent from /e/ OS on Fairphone3
Bug#1053549: New theme for docs in reStructuredText (was: Re: Bug#932957: #932957 Please migrate Release Notes to reStructuredText)
Hello Holger And since there has been a call for a Debian theme for Sphinx (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549), a proposal for that can be found at https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ (for those, who are uncomfortable with the greenish theme). I've had a quick look at the theme inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ and looks very nice both in my computer and my phone, and I think it's a good improvement for the current theme. Thank you *very much*. I don't know which is the better way forward, maybe add a repo for the theme in the ddp-team umbrella, and then file a bug for every documentation manual using Sphinx, suggesting including it? I also know there are some other bugs related to Debian Documentation using Sphinx (search box, javascript-related issues) but it's hard for me to find an enough-long chunk of time to look at them, apologies. Kind regards, -- Laura Arjona Reina https://wiki.debian.org/LauraArjona
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi again, Holger Wansing wrote (Mon, 13 Nov 2023 11:19:07 +0100): > Time for a status update: > Since the new release-notes itself are now being built on www-master (based > on Sphinx), some changings were needed for the webpage (currently > www.debian.org/releases/testing/releasenotes), because we no longer have > separate release-notes for the different release-archs. > > I did that yesterday, let's say as a proposal. > > Previously, there was some sort of black magic (or maybe it's perl), > which automatically creates a table with all architectures, languages, > and output formats of the r-n. > Changing this mechanism to leave out the architecture part is out of my > skills, but I managed to copy (and adapt) the logic which is being used in > the debian.org/doc part of the website, to generate the list of available > languages and formats for the different manuals there. > > It looks fine IMO, and it also works. However new languages are not > displayed automatically, so compared to the old mechanism there might > be some handwork needed at some point (but rare I guess). > > > @webmaster, @release-team, @ddp-team: what do you think? Would this > proposal be acceptable to you for the new release-notes (trixie and later)? And since there has been a call for a Debian theme for Sphinx (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549), a proposal for that can be found at https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ (for those, who are uncomfortable with the greenish theme). Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi, Paul Gevers wrote (Thu, 24 Aug 2023 14:10:41 +0200): > I have just requested webmaster to switch the bookworm build from the > master branch to the bookworm branch [1]. After that request gets merged > and deployed, I'd like you to publish your work in the master branch > such that we can work from there (and see the results too [2]). Because > in your worked we stopped making notes per architecture, we probably > need to make further changes to the webmaster archive, but let's first > build something. Time for a status update: Since the new release-notes itself are now being built on www-master (based on Sphinx), some changings were needed for the webpage (currently www.debian.org/releases/testing/releasenotes), because we no longer have separate release-notes for the different release-archs. I did that yesterday, let's say as a proposal. Previously, there was some sort of black magic (or maybe it's perl), which automatically creates a table with all architectures, languages, and output formats of the r-n. Changing this mechanism to leave out the architecture part is out of my skills, but I managed to copy (and adapt) the logic which is being used in the debian.org/doc part of the website, to generate the list of available languages and formats for the different manuals there. It looks fine IMO, and it also works. However new languages are not displayed automatically, so compared to the old mechanism there might be some handwork needed at some point (but rare I guess). @webmaster, @release-team, @ddp-team: what do you think? Would this proposal be acceptable to you for the new release-notes (trixie and later)? Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Created a new bug to track the MR https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13 That is https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053445 -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Package: www.debian.org Severity: normal [Re-send once more; first try one month ago did not make it into the BTS] Paul Gevers wrote (Thu, 24 Aug 2023 14:10:41 +0200): > Hi Holger, > > On 29-07-2023 21:29, Holger Wansing wrote: > > I have worked out the last big blocker for this migration now. > > That is, to allow the build on wolkenstein, which is happening via the > > parts/7release-notes script in webmaster-team/cron git repo. > > I have just requested webmaster to switch the bookworm build from the > master branch to the bookworm branch [1]. After that request gets merged > and deployed, I'd like you to publish your work in the master branch > such that we can work from there (and see the results too [2]). Because > in your worked we stopped making notes per architecture, we probably > need to make further changes to the webmaster archive, but let's first > build something. Hey webmaster team, please consider MR13 in webmaster's cron repo: https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13 Thanks Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Package: www.debian.org Severity: normal Paul Gevers wrote (Thu, 24 Aug 2023 14:10:41 +0200): > Hi Holger, > > On 29-07-2023 21:29, Holger Wansing wrote: > > I have worked out the last big blocker for this migration now. > > That is, to allow the build on wolkenstein, which is happening via the > > parts/7release-notes script in webmaster-team/cron git repo. > > I have just requested webmaster to switch the bookworm build from the > master branch to the bookworm branch [1]. After that request gets merged > and deployed, I'd like you to publish your work in the master branch > such that we can work from there (and see the results too [2]). Because > in your worked we stopped making notes per architecture, we probably > need to make further changes to the webmaster archive, but let's first > build something. Hey webmaster team, please consider MR13 in webmaster's cron repo: https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13 Thanks Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi, Paul Gevers wrote (Thu, 24 Aug 2023 14:10:41 +0200): > Hi Holger, > > On 29-07-2023 21:29, Holger Wansing wrote: > > I have worked out the last big blocker for this migration now. > > That is, to allow the build on wolkenstein, which is happening via the > > parts/7release-notes script in webmaster-team/cron git repo. > > I have just requested webmaster to switch the bookworm build from the > master branch to the bookworm branch [1]. After that request gets merged > and deployed, I'd like you to publish your work in the master branch > such that we can work from there (and see the results too [2]). Because > in your worked we stopped making notes per architecture, we probably > need to make further changes to the webmaster archive, but let's first > build something. Please note, that the webmaster-team/cron script has to be overworked, to deal with the new reST format. I have prepared that in https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads (as written above). Rationale: It is common for all documentation packages we have on www.debian/doc, that the package itself creates files during package build, which do not fit into the webpage system (main point: content negotiation). To deal with this, someone from the ddp team has developed a script (long ago; don't know by head who was this), that renames the files to fit the webpage (basically this is about adding the language extension). This is in webmaster-team/cron/parts/7doc. With the old docbook release-notes, this has been dealed with directly in the build script. Now in the new reST world, I have basically copied the whole build mechanism from the developers-reference as is, with the intention to rely on the mechanism from the 7doc script mentioned above (the 7doc script has been adapted explicitly for reST/sphinx). The release-notes have always been a corner case when it comes to how they were built, compared to all other docs: the r-n are built from source explicitly for the website, while for all the other documentation we just unpack their binary debian packages, rename the files via 7doc and that's it. This does not work for the r-n, because there is no Debian package existing for them. So the r-n are always a separate world. Based on that, I have kept the 7doc mechanism separately too, copied into the new 7release-notes. Means the 7release-notes script from webmaster-team/cron git repo gets extremely expanded, to copy (and adjust) the functionality from 7doc. I have developed and tested this here locally, it should work fine. So I have created a merge request to get this done for the website: https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13 Best regards Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi Holger, On 29-07-2023 21:29, Holger Wansing wrote: I have worked out the last big blocker for this migration now. That is, to allow the build on wolkenstein, which is happening via the parts/7release-notes script in webmaster-team/cron git repo. I have just requested webmaster to switch the bookworm build from the master branch to the bookworm branch [1]. After that request gets merged and deployed, I'd like you to publish your work in the master branch such that we can work from there (and see the results too [2]). Because in your worked we stopped making notes per architecture, we probably need to make further changes to the webmaster archive, but let's first build something. Paul [1] https://salsa.debian.org/webmaster-team/cron/-/merge_requests/12 [2] https://www.debian.org/releases/testing/releasenotes OpenPGP_signature.asc Description: OpenPGP digital signature
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi, Richard Lewis wrote (Sun, 30 Jul 2023 21:32:36 +0100): > sorry - it's the use of italic in eg '# apt-mark auto rsyslog' > https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#changes-to-system-logging > > > i found > https://stackoverflow.com/questions/16397794/how-to-show-terminal-shell-code-snippets-in-sphinx > which i think says that 'code-block:: console' might be better than > 'code-block:: shell', but i may be misunderstanding that page Yes, 'code-block:: console' indeed works fine for most occurrences. So I unified 'code-block:: text' 'code-block:: shell' 'code-block:: shell-session' to 'code-block:: console' The only case where that doesn't work is, when substitutions are included. They only work within '.. parsed-literal::' sadly :-( Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Holger Wansing writes: > Richard Lewis wrote (Sun, 30 Jul 2023 > 11:10:10 +0100): >> in [0] the '#' is meant to indicate 'run this as root', but the rst has >> '.. code-block:: shell' so the commands are being formatted as a >> comment. > > Yes, there are different methods for including quoted material, and they are > somewhat tricky sometimes. > > I may lack detailed experience on this, so need more details: > - What's the exact URL where you found this? (there was no such link as [0]) > - What makes you think, that the commands are formatted as comment? > Is it the font color or what? sorry - it's the use of italic in eg '# apt-mark auto rsyslog' https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#changes-to-system-logging i found https://stackoverflow.com/questions/16397794/how-to-show-terminal-shell-code-snippets-in-sphinx which i think says that 'code-block:: console' might be better than 'code-block:: shell', but i may be misunderstanding that page
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi, Richard Lewis wrote (Sun, 30 Jul 2023 11:10:10 +0100): > in [0] the '#' is meant to indicate 'run this as root', but the rst has > '.. code-block:: shell' so the commands are being formatted as a > comment. Yes, there are different methods for including quoted material, and they are somewhat tricky sometimes. I may lack detailed experience on this, so need more details: - What's the exact URL where you found this? (there was no such link as [0]) - What makes you think, that the commands are formatted as comment? Is it the font color or what? > in [1] the second para is dummy text that is commented out in the XML > version. This reST version of r-n is kind of a draft, so it's not as ready as it would be when in publication mode. Such details slipped through, sorry. > In the rst 'source' (but not visible in the html) there are > also some odd chars around 'formal' (the quotes seems to be fine in the > sections above). Reason for this was: there were different quote signs used in those sections. I changed “this” quotes into "this" ones. That solves the problem. > [1] > https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#things-to-do-post-upgrade-before-rebooting > > in [2] there seems to be an extra space in the RH column in > 'c a-certificates-java' (in the source there is a linebreak after the c) Also fixed. However, this section is also kind of a placeholder, it will get replaced with a updated list. But fixing the format is a good idea nevertheless. > [2] > https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#known-severe-bugs > > (And > https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/about.en.html#sources-for-this-document > will need an update! - as will the README in salsa) For sure. I am aware of this. Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Holger Wansing writes: > Tests were successful, the results can be found on > https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/, > in the exact same structure as they would appear on the Debian > website. nice - it looks like it's come on a long way from the previous version. A couple of minor things in the content: in [0] the '#' is meant to indicate 'run this as root', but the rst has '.. code-block:: shell' so the commands are being formatted as a comment. in [1] the second para is dummy text that is commented out in the XML version. In the rst 'source' (but not visible in the html) there are also some odd chars around 'formal' (the quotes seems to be fine in the sections above). [1] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#things-to-do-post-upgrade-before-rebooting in [2] there seems to be an extra space in the RH column in 'c a-certificates-java' (in the source there is a linebreak after the c) [2] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#known-severe-bugs (And https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/about.en.html#sources-for-this-document will need an update! - as will the README in salsa)
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi, I have worked out the last big blocker for this migration now. That is, to allow the build on wolkenstein, which is happening via the parts/7release-notes script in webmaster-team/cron git repo. I forked that repo and committed my changings there: https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads Tests were successful, the results can be found on https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/, in the exact same structure as they would appear on the Debian website. The release-notes dir https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/ holds the html files for all languages, but content negotiation does not work there apparently; and the apache server does not show a file browser view for that directory. You can find German for example via https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.de.html or Dutch via https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.nl.html And remember, there is only one generic variant for all archs now! The build process in 7releases-notes is now different between stable and testing: stable is still on docbook, and testing is on sphinx/ reStructuredText. So, when the time comes, we could create a bookworm branch for r-n, migrate master to sphinx, and activate the build on wolkenstein for master/trixie. That way, we have a comfortable test time, to get everything ready on the website (Note: there are changings to do on the website then), while the r-n for trixie are not in public attention. So long Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
[ Sending this to #932957 as well, as it contains valueable info on that topic ]
Jeremy Stanley wrote (Wed, 24 May 2023 18:22:09 +):
> On 2023-05-24 19:40:56 +0200 (+0200), Agathe Porte wrote:
> [...]
> > Maybe the idea was to introduce %OLD_RELEASE_NAME% and to call sed to
> > replace this kind of strings in a build step, and not rely on sphinx
> > substitution at all.
> >
> > I know that I have done this a few times and it works fine as a very
> > simple preprocessor.
>
> Similar things can be done at sphinx-build time with a custom Sphinx
> extension (can be a trivial Python module). We do that for the
> published security advisories list upstream in OpenStack:
>
> https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/conf.py#L31
>
> https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/_exts/vmt.py
>
> That's a more complex example because we generate a ton of content
> out of structured data (YAML) files by splatting the relevant fields
> into substitutions in a Jinja2 template, but for basic string
> substitution you could get away with something far simpler, or even
> use a canned one like (this was simply my first web search result):
>
> https://pypi.org/project/Sphinx-Substitution-Extensions/
>
> The examples in its readme look to be along the lines of the Debian
> Release Notes use case anyway. There's also basic substitutions
> support in the reStructuredText specification, which might be useful
> to reduce the amount of actual content you need to swap at build
> time:
>
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
The above seem related to the issue in question, but the solution pointed
out by James Addison in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932957#90
(use parsed-literal ('.. parsed-literal::') blocks)
seems to be the easier one (at least for this document) and it works fine
here. So I would go for it.
Thanks anyway
Holger
--
Holger Wansing
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi Paul, Am 23. Mai 2023 08:20:18 MESZ schrieb Paul Gevers : >Hi Holger, > >On 18-05-2023 22:39, Holger Wansing wrote: >> I worked on this recently, and I have something like a prototype ready. > >Thanks a lot for working on this. I'm a bit swamped with last minute things >that need to happen before the release of bookworm, so I don't expect to have >time to look at this until after the release. As I wrote, I see this as a prototype, and thus I don't expected it to be a thing to happen before releasing bookworm. Holger -- Sent from /e/ OS on Fairphone3
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi Holger, On 18-05-2023 22:39, Holger Wansing wrote: I worked on this recently, and I have something like a prototype ready. Thanks a lot for working on this. I'm a bit swamped with last minute things that need to happen before the release of bookworm, so I don't expect to have time to look at this until after the release. Paul OpenPGP_signature Description: OpenPGP digital signature
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi, Richard Lewis wrote (Fri, 19 May 2023 00:58:26 +0100): > On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing > wrote: > 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 copied style and font settings from developers-reference, another document, which has been migrated recently from docbook to sphinx. So I consider this as a quasi-standard at the moment. I copied it by intent, to get a consistent look for all manuals generated with sphinx. We can work on that later on, as Laura already pointed out there is even a bugreport for this. So will ignore this for now here. > - 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" The first version I built with sphinx had version displayed "release-notes 5.0.1" which confused me even more. Therefore I changed that in the sense of "release-notes version 12 for Debian release 12". Can still be changed in any way... > - 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?) I see this in other sphinx-generated manuals as well. So maybe a bug in sphinx? Or a feature? > - 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) good catch, that should be changed - that's an easy one :-) > - 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. Seems to be the default in Sphinx? Currently I cannot see how I could change that. > - > https://people.debian.org/~holgerw/release-notes_sphinx/en/html/genindex.html > is completely blank Yes, I already noticed that too. And it's the same for the debian-policy and the developers-reference... Needs to be investigated. > - not sure "show source" on the left is all that useful for readers That's a feature of sphinx, I guess. And if a reader finds an error, or wants to make a proposal for a change, he can easily access the source code and provide a patch against this. So that's a good feature! > 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 I have removed several old files from the repo now, amongst others the dbk files in en. The new rst files for English are in ./source/ (default for sphinx AFAICT). > > 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//bookworm/g' etc before "building" with sphinx. That will not work. You cannot replace all 'bullseye' by 'bookworm'. There are places, where the 'bullseye' needs to stay. So that needs to be done selective one-by-one. > 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? Sure, in sphinx that's called "substitution" and I use it already very much in this manual. The point is, that they do not work in all situations, where they did in docbook (at least this is my current state of knowledge). Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
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 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//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
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing 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//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?
Bug#932957: #932957 Please migrate Release Notes to reStructuredText
[[ debian-devel in CC, to get a wider audience regarding reStructuredText ]] Hi, 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/ while the git repo containing the migration is at https://salsa.debian.org/holgerw/release-notes However, I may have some objections against the migration at all: 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. In docbook speach these were entities, and you could use them in URLs like this: Please follow the instructions in the https://www.debian.org/releases//releasenotes;>Release Notes for to upgrade to first if needed. Please note the in the URL! I could not get this working with sphinx (if someone knows better, please contact me!) In sphinx, I used hardcoded codenames like https://www.debian.org/releases/bullseye/releasenotes instead, which means, that there is much work to do to make the release-notes fit for the next release, while with docbook you only need to change the entity in one place !!! In sphinx you need to change every single occurence, and don't forget the translations !!! Beside this, I need help to adapt the buildchain, to get the possibility of building the release-notes for the different architectures. I have no python knowledge, so I will most likely not get this running myself. And the last point is the integration into the debhelper tools: I don't know if it is required, to have the release-notes fit for building as a whole package with sbuild or debuild or similar. Salsa tries to build it via CI at every push, but currently fails. However, there is no package "release-notes" in the archive, so currently it is only a matter of building it on wolkenstein for www.debian.org, right? Regards Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
