Duplication of docs in analysis & examples

[IAlibay]

We are getting a lot of "duplicate label" issues when building the docs.

Took me far too long to debug, but it turns out that the issue is that we have parts of the docs that appear twice under two difference sections.

For example; https://userguide.mdanalysis.org/stable/examples/analysis/alignment_and_rms/README.html
and
https://userguide.mdanalysis.org/stable/examples/analysis/README.html#alignments-and-rms-fitting

are actually the same thing, but just in two different places.

Additionally, we have cases where we end up with pages that are accessible only under analysis, but are technically present under examples, for example: https://userguide.mdanalysis.org/stable/examples/analysis/hydrogen_bonds/hbonds.html

I realise some pages might be relevant in two different sections, but this might actually be more confusing than anything else. In my opinion, we need to work out how best to handle this and clean up accordingly.

[IAlibay]

Relevant warning messages:

/home/bioc1523/github/UserGuide/doc/source/examples/analysis/alignment_and_rms/README.rst:7: WARNING: duplicate label alignment-and-rms, other instance in /home/bioc1523/github/UserGuide/doc/source/examples/analysis/README.rst
/home/bioc1523/github/UserGuide/doc/source/examples/analysis/hydrogen_bonds/README.rst:7: WARNING: duplicate label hydrogen-bonds, other instance in /home/bioc1523/github/UserGuide/doc/source/examples/analysis/README.rst
/home/bioc1523/github/UserGuide/doc/source/examples/analysis/trajectory_similarity/README.rst:6: WARNING: duplicate label trajectory-similarity, other instance in /home/bioc1523/github/UserGuide/doc/source/examples/analysis/README.rst

[jandom]

For anybody working on this, the build can be made to error with

make html SPHINXOPTS="-W --keep-going"

But obviously it's fixing the warnings that will take 99% of the work, not setting this flag as the default

[mhmohona]

Hello @IAlibay, may I work on this issue?

[RMeli]

@mhmohona sure, you are welcome to work on the issue. However, there is some discussion that needs to happen.

we need to work out how best to handle this and clean up accordingly

Please discuss here your suggested solution. When there is consensus on how to address this issue, then it can be fixed accordingly.

[mhmohona]

@RMeli So I ran make html SPHINXOPTS="-W --keep-going command and got following error -

is addressing these errors enough to solve this issue? Or do I need to do manual review through out the document?

[mhmohona]

Hey @RMeli, I’ve compiled a detailed table outlining the current status, duplication levels, and recommended actions across MDAnalysis resources (User Guide, website, Docs, and GitHub Wiki). Please review and let me know if further adjustments are needed.

Page Name	Platforms	Duplication Level	Unique Content	Recommended Action	Role & Cross-Linking Plan
Installation	User Guide, Main Website, Docs, GitHub	100%	User Guide: Detailed pip/conda instructions, Docs: Technical notes	Consolidate into User Guide with quick links from website and GitHub	User Guide: Primary source, website points users to Guide; GitHub Wiki focuses on community troubleshooting for installation issues
Quick Start	User Guide, Main Website	80%	User Guide: Expanded examples, Website: Minimal setup steps	Keep primary content in User Guide; website provides a concise intro with link	Cross-link from website homepage and Docs to the User Guide quick start page
Features	User Guide, Main Website	70%	User Guide: Feature examples, Website: Overview	Retain overview on website; link detailed content to User Guide	Add section on homepage linking to User Guide’s advanced features with examples
Tutorials	User Guide, GitHub Wiki	60%	Wiki: Archived tutorials, User Guide: Latest tutorials	Archive older tutorials in Wiki, redirect to User Guide for updated versions	Tutorials guide users to relevant sections in Docs and FAQs for deeper exploration
Troubleshooting	Docs, GitHub Wiki	50%	Docs: Structured troubleshooting steps, Wiki: User-generated Q&A	Keep structured troubleshooting in Docs, use Wiki for discussions	Docs link to GitHub Discussions for community solutions and follow-ups
FAQ	Website, GitHub Wiki, User Guide	40%	Different questions across platforms	Merge FAQs into User Guide, cross-link from other locations	Add a “Search FAQ” option on the website linking to User Guide FAQs
Privacy Policy	Dedicated Page	100%	Uniform across platforms	Keep as-is with references across all platforms	Link from all main platforms to the central privacy policy page
Core Objects	Docs, User Guide	80%	Docs: API details, User Guide: Practical usage	Keep API info in Docs, move examples to User Guide	Cross-link technical API documentation from User Guide practical examples
Group Operations	Docs, User Guide	75%	User Guide: Application-based, Docs: API-level details	Retain API documentation in Docs, practical usage in User Guide	Link User Guide examples directly to API methods in Docs
Contributing	User Guide, GitHub Wiki	50%	User Guide: Detailed process, Wiki: Short guidelines	Move full process to User Guide, leave Wiki for quick tips	Create a contribution workflow diagram with cross-links between User Guide and GitHub