Bug 31657 - [DOCS] Fix the cause of duplicate label warning messages when generating the manual
Summary: [DOCS] Fix the cause of duplicate label warning messages when generating the ...
Status: CLOSED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Main
Hardware: All All
: P5 - low normal
Assignee: Katrin Fischer
QA Contact: David Nind
URL:
Keywords:
Depends on:
Blocks: 31658
  Show dependency treegraph
 
Reported: 2022-09-29 19:36 UTC by David Nind
Modified: 2023-06-08 22:26 UTC (History)
2 users (show)

See Also:
GIT URL:
Initiative type: ---
Sponsorship status: ---
Comma delimited list of Sponsors:
Crowdfunding goal: 0
Patch complexity: ---
Documentation contact: Katrin Fischer + Caroline Cyr La Rose
Documentation submission: Merge requests 591 and 593
Text to go in the release notes:
Version(s) released in:
Circulation function:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description David Nind 2022-09-29 19:36:49 UTC
When generating the HTML version of the manual, there are a lot of duplicate label warning messages.

This makes identifying and addressing other warning messages more of a challenge.
Comment 1 David Nind 2022-09-29 19:53:47 UTC
This issue was raised on the GitLab issues queue: https://gitlab.com/koha-community/koha-manual/-/issues/18

Caroline Cyr La Rose has identified the cause of the issue[1] and a solution:

- Caused by: 'sphinx.ext.autosectionlabel' setting in conf.py

- Proposed solution: 

  . update conf.py to remove setting: 'sphinx.ext.autosectionlabel',

  . change references to system preferences from: :ref:`SystemPreferenceName`

 . to: :ref:`SystemPreferenceName <systempreferencename-label>`

[1] https://www.spinics.net/lists/linux-doc/msg77015.html
Comment 2 David Nind 2022-09-29 20:00:59 UTC
My suggested plan is to update these progressively - maybe a manual section/chapter at a time - as there are a lot of these to update!

For each chapter/section being worked on, create a separate bug and link back in 'Depends on' to this omnibus bug - unless anyone else has a better idea.

By the time it is finished this should have reduced the warning messages considerably - for me working locally, there currently there are 282 warning messages when the HTML output is produced.
Comment 3 David Nind 2022-09-29 20:04:27 UTC
Caroline, I've added you to the bug.
Comment 4 Katrin Fischer 2022-09-30 19:44:57 UTC
I am working on patches for this, hope to have something to show soon.
Comment 5 David Nind 2022-09-30 19:53:13 UTC
Thanks Katrin!
Comment 6 Katrin Fischer 2022-09-30 20:22:02 UTC
First patch up:
https://gitlab.com/koha-community/koha-manual/-/merge_requests/591

It did seem to work ok when I created the html files locally.
Comment 7 Caroline Cyr La Rose 2022-09-30 21:35:04 UTC
A note to remember that we'll have to change the rst syntax cheatsheet on the wiki
Comment 8 Katrin Fischer 2022-09-30 22:46:09 UTC
I believe between Caroline's and my merge requests we should have taken care of all of them now. I suggest we remove the autosectionlabel after these are merged and then fix anything that remains.
Comment 9 Caroline Cyr La Rose 2022-10-03 16:38:16 UTC
(In reply to Caroline Cyr La Rose from comment #7)
> A note to remember that we'll have to change the rst syntax cheatsheet on
> the wiki

This is done
Comment 10 David Nind 2022-10-04 13:26:21 UTC
Woot!

Thanks Katrin and Caroline for all your speedy work on updating all the refs and fixing the casue of error messages!

The manual is now generated without any warning or other error messages!

David