Bug 31657

Summary: [DOCS] Fix the cause of duplicate label warning messages when generating the manual
Product: Koha Reporter: David Nind <david>
Component: DocumentationAssignee: Katrin Fischer <katrin.fischer>
Status: CLOSED FIXED QA Contact: David Nind <david>
Severity: normal    
Priority: P5 - low CC: caroline.cyr-la-rose, david
Version: Main   
Hardware: All   
OS: All   
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:
Bug Depends on:    
Bug Blocks: 31658    

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