Fix documentation links

[tautschnig]

1. Make sure .c source files are considered by Doxygen. (Notably, cprover_contracts.c contains relevant documentation.)
2. Reference other files in ways understood by Doxygen.

• Each commit message has a non-empty body, explaining why the change was made.
• n/a Methods or procedures I have added are documented, following the guidelines provided in CODING_STANDARD.md.
• The feature or user visible behaviour I have added or modified has been documented in the User Guide in doc/cprover-manual/
• n/a Regression or unit tests are included, or existing tests cover the modified code (in this case I have detailed which ones those are in the commit message).
• n/a My commit message includes data points confirming performance improvements (if claimed).
• My PR is restricted to a single feature or bugfix.
• n/a White-space or formatting changes outside the feature-related changed lines are in commits of their own.

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (014188e) 78.50% compared to head (ccf1e61) 78.50%.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #7578   +/-   ##
========================================
  Coverage    78.50%   78.50%           
========================================
  Files         1670     1670           
  Lines       191767   191767           
========================================
  Hits        150548   150548           
  Misses       41219    41219           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[thomasspriggs]

ℹ️ Removing this use of \subpage means that the Central Data Structures page is no longer considered a sub page of the architecture page which moves it to the root level in the navigation tree.

[thomasspriggs]

This change seems to break the link. When I build the documentation site locally it now links to here -

I think this link should not be updated as it seems to be working already for the generated website and is not included in the list of errors in this issue - #7576

[tautschnig]

Thank you very much for careful checking! It seems that some other warning got me confused. I have now reverted this change.

[thomasspriggs]

The old link here works for the built doxygen website, but doesn't work when viewing as github markdown. The new link works when viewing as github markdown, but not when viewing the doxygen website. I haven't been able to work out a link format which works both ways round.

The root of these problems as I understand it is that doxygen formatted input files are not github markdown formatted input files. Github markdown does not support doxygens tags and doxygen doesn't work with github markdown links. Therefore there are features for one file format which don't work for the other, making the files correct for one can result in broken links or raw tags being displayed in the other.

As I understand it, the build system attempts to work around this problem for the files in /doc/cprover-manual by attempting to rewrite the links from github markdown format into doxygen format. But it can't be run over the rest of the docmentation tree as the pandoc + pythonscript based solution doesn't understand doxygen tags and will break them in the process. This includes the tags for dot diagrams and sub page organisation among others.

[tautschnig]

We already used links to ../../src/goto-symex/ several times in this file, but indeed those were just broken. I have now fixed all of them (and left the above as it was before).