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?