[SCHEMATIC-320] Standardize and Update Documentation Pages

[SageGJ]

Problem:

• There were appx 40 errors within our rst documentation pages related to namespace collisions and formatting
• Section headers and hierarchy can be anything within sphinx, and hierarchy is determined by order of appearance. Thus, when having different conventions between files, it can be difficult to determine the type of section each section is by looking. This would also complicate configuring settings across the documentation as a whole since the same type of section can be indicated with different characters.
• There also existed a number of broken links

Solution:

• Unique section names were added where duplicates existeed
• Section headers were all updated to follow the sphinx/python convention since we use sphinx.
• Links were updated where appropriate.

Testing:

• VSCode is showing no errors in the docs directory (see below)
• Documentation pages were reviewed
  

Reviewing Instructions

Please review the documentation and

• test links within pages
• give feedback on organization of information
• content of the documentation was largely left unchanged, but if something could be clarified please point that out as well.

[BryanFauble]

For those reviewing here is a link to the rendered doc pages:
https://schematicpy--1624.org.readthedocs.build/en/1624/

[Copilot]

Pull Request Overview

This PR standardizes section headings, updates reference links, and fixes formatting inconsistencies across multiple .rst files to align with the Sphinx/python conventions and resolve broken links.

• Converted all section headings to use consistent adornment (e.g., #, *, =, ^, etc.).
• Updated cross-reference targets and ref links to match defined labels.
• Removed formatting errors and one duplicated paragraph.

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
validation_rules.rst	Standardized headings and increased :depth: in table of contents
tutorials.rst	Applied uniform heading adornments for sections
troubleshooting.rst	Added consistent heading markup for subsections
manifest_validation.rst	Replaced underlines, updated ref links, but left one hyphen line
manifest_submission.rst	Standardized headings and updated configuration ref link
manifest_generation.rst	Unified heading styles and updated internal refs
linkml.rst	Standardized headings; duplicated paragraph remains
jsonschema_generation.rst	Corrected CLI ref targets to full cli_reference anchors
installation.rst	Updated heading adornments and anchor links
index.rst	Applied # adornment for main title
configuration.rst	Converted heading levels to # for major sections
conf.py	Added autosectionlabel_prefix_document = True
cli_reference.rst	Standardized top-level heading; unified subcommand titles
asset_store.rst	Aligned section headers with new style patterns

Comments suppressed due to low confidence (4)

docs/source/linkml.rst:10

• This paragraph is duplicated back-to-back. Remove the redundant text block to improve readability.

DPE is currently looking into what the future of Schematic might look like. This includes the possibility of completely reworking how we handle data models. Currently, Schematic supports data models in CSV or JSON-LD format. Several DCCs are either using or planning on using LinkML to create their data models and then port them to JsonLD for use in schematic. One possibility in Schematic 2.0 (placeholder name) is to make LinkML the format for data models and to use native LinkML functionality where possible to reduce the work that Schematic does. DPE is currently looking into what the future of Schematic might look like. This includes the possibility of completely reworking how we handle data models. Currently, Schematic supports data models in CSV or JSON-LD format. Several DCCs are either using or planning on using LinkML to create their data models and then port them to JsonLD for use in schematic. One possibility in Schematic 2.0 (placeholder name) is to make LinkML the format for data models and to use native LinkML functionality where possible to reduce the work that Schematic does.

docs/source/manifest_validation.rst:44

• You’ve added '*' adornments above and below 'Requirements' but left the old hyphen underline. Remove this redundant hyphen line to keep a single, consistent heading style.

************

docs/source/manifest_validation.rst:13

• The ref target 'installation:6. Set up configuration files' doesn’t match the defined anchor. Update it to the actual label (e.g., installation:Set up configuration files) or adjust the anchor to match.

Ensure you have a Synapse account and set up Synapse configuration file correctly. See the :ref:`setting up configuration files <installation:6. Set up configuration files>` section for more details.

docs/source/manifest_submission.rst:11

• The ref target 'installation:6. Set up configuration files' is likely incorrect; align it with the actual anchor name, such as installation:Set up configuration files.

Ensure you have a Synapse account and set up Synapse configuration file correctly. See the :ref:`setting up configuration files <installation:6. Set up configuration files>` section for more details.

[BryanFauble]

I gave these changes a read and tabbed around the readthedocs pages. Didn't find anything broken!

[SageGJ]

For those reviewing here is a link to the rendered doc pages:
https://schematicpy--1624.org.readthedocs.build/en/1624/

@BryanFauble thanks for sharing that! That link is also included in the PR description under the Reviewing Instructions section

Also thanks for taking a look through!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[andrewelamb]

@SageGJ Every link I tried worked!

[SageGJ]

@andrewelamb thanks for reviewing!