Reference documentation restructure + refactor

[lzdanski]

Description

This PR restructures the Reference Section, creates the new Guides>Connect database section from the existing Profiles Overview page. It replaces #2424.

• It removes the redundant Profile Config page -> this refactoring would have had two different "Profiles" pages in the reference section
• Adds the Profiles mappings to the Reference sidebar and hides the list of profile mappings from the Profiles Index overview.

• Moves the contents of the Profiles Index Overview page into three new pages in the Connect database section. NOTE - due to issue in local build, the sidebar appears inconsistent in screenshots.

• Discussion question: disabling dbt event tracking might not fit on the current page in the "Connect Database", and would need to be relocated.

Related Issue(s)

Breaking Change?

Possible docs broken links. Moved files have been compared to the list of redirects created to reduce this possibility.

Checklist

• I have made corresponding changes to the documentation (if required)
• I have added tests that prove my fix is effective or that my feature works

[pankajastro]

Hi @lzdanski, do we still generate the profiles .rst docs automatically? I want to confirm whether we actually need to check in these profile files

[pankajastro]

Could you please resolve the merge conflict?

[lzdanski]

Thanks for the review @pankajastro

1. Merge conflict addressed
2. Checking out the GitHub workflows, the netlify.toml file looks like it kicks off a build as part of deployment, so I will remove the auto-generated profiles from this PR: https://github.com/astronomer/astronomer-cosmos/blob/main/netlify.toml#L27

[pankajastro]

Hi @lzdanski, I tried running it on my local machine, and it looks like the docs are rendering a bit differently from the screenshot you shared in the description. For example:

ProfileConfig is missing in the left menu

Profile Overview appears twice

And also I think the CosmosConfig is missing in the left menu

[pankajastro]

Also getting the following warning

reading sources... [100%] reference/profiles/index
/Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/reference/index.rst:10: WARNING: toctree contains reference to nonexisting document 'reference/configs/project-conf'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/profiles/index.rst: WARNING: document isn't included in any toctree
/Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/reference/configs/cosmos-conf.rst: WARNING: document isn't included in any toctree
done

[pankajastro]

I tried to run locally, and I'm seeing the following errors in the log

updating environment: [config changed ('redirects')] 113 added, 0 changed, 3 removed
reading sources... [100%] reference/profiles/index
/Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/guides/connect_database/profile-customise-per-node.rst:4: WARNING: duplicate label profile-customise-per-node, other instance in /Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/profiles/index.rst
/Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/profiles/index.rst:134: WARNING: duplicate label profile-customise-per-node, other instance in /Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/guides/connect_database/profile-customise-per-node.rst
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/pankaj/Documents/astro_code/astronomer-cosmos/docs/profiles/index.rst: WARNING: document isn't included in any toctree

The left menu appears to be in a different order than the index page content, which feels inconsistent.

[pankajastro]

Left one minor comment: #2443 (comment) — otherwise looks good.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.98%. Comparing base (88319b2) to head (c0f92e9).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2443   +/-   ##
=======================================
  Coverage   97.98%   97.98%           
=======================================
  Files         103      103           
  Lines        7086     7086           
=======================================
  Hits         6943     6943           
  Misses        143      143           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.