Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR starts migrating Ascender’s documentation and doc theming away from upstream Ansible/AWX references, while also updating the UI/API help links to point at the new Ascender documentation site.
Changes:
- Introduces a custom Sphinx theme (
sphinx_ascender_theme) based onsphinx_rtd_theme, including a version chooser, custom header/footer, and branding assets. - Moves/updates RBAC documentation content into
security.rstand removes legacy standalone pages (e.g.,rbac.rst,insights.rst) from the user guide toctree. - Updates UI and API “Help” links to use
https://docs.ascender-automation.organd adjusts paths (drops the/html/prefix).
Reviewed changes
Copilot reviewed 64 out of 167 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| pyproject.toml | Enables setuptools_scm config (currently conflicts with existing version-override approach). |
| docs/docsite/sphinx_ascender_theme/version_chooser.html | Adds dropdown version switcher logic. |
| docs/docsite/sphinx_ascender_theme/theme.conf | Defines theme inheritance from sphinx_rtd_theme and theme options. |
| docs/docsite/sphinx_ascender_theme/static/images/AscenderAuto_icon_clr.svg | Adds Ascender SVG branding asset. |
| docs/docsite/sphinx_ascender_theme/static/images/AscenderAuto_icon_clr_S.png | Adds Ascender PNG branding asset. |
| docs/docsite/sphinx_ascender_theme/static/css/rtd-ethical-ads.css | Adds small CSS override for RTD ethical ads styling. |
| docs/docsite/sphinx_ascender_theme/static/css/ansible.css | Adds large stylesheet (largely RTD/Ansible-derived) for doc appearance. |
| docs/docsite/sphinx_ascender_theme/searchbox.html | Overrides searchbox to optionally include version chooser. |
| docs/docsite/sphinx_ascender_theme/rtd-ethical-ads.html | Adds ethical ads placement block for RTD builds. |
| docs/docsite/sphinx_ascender_theme/layout.html | Overrides RTD layout to inject Ascender branding/header/footer and extra nav. |
| docs/docsite/sphinx_ascender_theme/footer.html | Overrides RTD footer to inject “built with” block. |
| docs/docsite/sphinx_ascender_theme/extranav.html | Adds optional HubSpot sidebar banner include. |
| docs/docsite/sphinx_ascender_theme/extrahead.html | Adds optional Swift/Tag Manager head elements. |
| docs/docsite/sphinx_ascender_theme/extrafooter.html | Adds placeholder footer include. |
| docs/docsite/sphinx_ascender_theme/extrabody.html | Adds top nav links and doc header logo/title region. |
| docs/docsite/sphinx_ascender_theme/built_with.html | Adds “Built with Sphinx … theme …” footer text. |
| docs/docsite/sphinx_ascender_theme/init.py | Adds Python theme package entrypoint/setup and defaults. |
| docs/docsite/rst/userguide/security.rst | Adds/relocates RBAC documentation content into security guide. |
| docs/docsite/rst/userguide/rbac.rst | Removes legacy RBAC page (content moved). |
| docs/docsite/rst/userguide/projects.rst | Updates SCM/projects wording (removes Insights mention). |
| docs/docsite/rst/userguide/project-sign.rst | Adjusts section heading formatting (and contains a typo to fix). |
| docs/docsite/rst/userguide/jobs.rst | Heading underline formatting change. |
| docs/docsite/rst/userguide/job_capacity.rst | Heading underline formatting change. |
| docs/docsite/rst/userguide/insights.rst | Removes legacy Insights page. |
| docs/docsite/rst/userguide/index.rst | Updates community/help links and removes rbac/insights from toctree. |
| docs/docsite/rst/userguide/ee_reference.rst | Heading underline formatting change. |
| docs/docsite/rst/upgrade_migration/upgrade_considerations.rst | Heading underline formatting change. |
| docs/docsite/rst/upgrade_migration/index.rst | Updates community/help links. |
| docs/docsite/rst/rest_api/index.rst | Updates community/help links and heading formatting. |
| docs/docsite/rst/rest_api/_swagger/swagger.py | Removes unused pkg_resources import. |
| docs/docsite/rst/release_notes/relnotes.rst | Updates release notes index entries and fixes release notes URL scheme. |
| docs/docsite/rst/release_notes/index.rst | Updates community/help links. |
| docs/docsite/rst/quickstart/login_superuser.rst | Normalizes placeholder casing for server name. |
| docs/docsite/rst/quickstart/index.rst | Updates community/help links and heading formatting. |
| docs/docsite/rst/quickstart/examine_dashboard.rst | Heading underline formatting change. |
| docs/docsite/rst/index.rst | Updates docsite root title/branding text. |
| docs/docsite/rst/contributor/work_items.rst | Updates community/help links (still contains some GitHub links missing scheme). |
| docs/docsite/rst/contributor/setting_up.rst | Heading underline formatting change (and contains a GitHub link missing scheme). |
| docs/docsite/rst/contributor/report_issues.rst | Updates community/help links (and contains GitHub links missing scheme). |
| docs/docsite/rst/contributor/intro.rst | Updates contributor intro help link. |
| docs/docsite/rst/contributor/index.rst | Updates contributor guide title and help link text. |
| docs/docsite/rst/administration/troubleshooting.rst | Heading underline formatting changes. |
| docs/docsite/rst/administration/tipsandtricks.rst | Multiple heading underline formatting changes. |
| docs/docsite/rst/administration/logfiles.rst | Heading underline formatting changes. |
| docs/docsite/rst/administration/init_script.rst | Heading underline formatting change. |
| docs/docsite/rst/administration/index.rst | Heading underline formatting changes and removes “Join us online” section. |
| docs/docsite/rst/administration/custom_rebranding.rst | Heading underline formatting changes. |
| docs/docsite/rst/administration/configure_ascender.rst | Heading underline formatting changes. |
| docs/docsite/rst/administration/clustering.rst | Table formatting/alignments and heading underline adjustments. |
| docs/docsite/requirements.txt | Modifies doc build dependency lockfile (currently leaves sphinx unpinned). |
| docs/docsite/conf.py | Switches doc theme to sphinx_ascender_theme, updates titles/dates/paths. |
| awx/ui/src/util/getDocsBaseUrl.js | Switches docs base URL to https://docs.ascender-automation.org (leaves dead code). |
| awx/ui/src/screens/Template/WorkflowJobTemplateVisualizer/VisualizerToolbar.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Template/WorkflowJobTemplateVisualizer/Modals/NodeModals/NodeTypeStep/NodeTypeStep.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Template/Survey/SurveyQuestionForm.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Template/shared/JobTemplate.helptext.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Setting/Subscription/SubscriptionEdit/SubscriptionStep.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Project/shared/ProjectSubForms/GitSubForm.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Project/ProjectDetail/ProjectDetail.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/NotificationTemplate/shared/CustomMessagesSubForm.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Inventory/shared/Inventory.helptext.js | Updates docs link paths (drops /html/). |
| awx/ui/src/screens/Inventory/shared/ConstructedInventoryHint.js | Updates docs link paths (drops /html/). |
| awx/ui/src/components/Search/AdvancedSearch.js | Updates docs link paths (drops /html/). |
| awx/ui/src/components/Lookup/HostFilterLookup.js | Updates docs link paths (drops /html/). |
| awx/ui/src/components/AppContainer/PageHeaderToolbar.js | Re-enables Help dropdown item and points it at Ascender docs. |
| awx/templates/rest_framework/api.html | Updates API guide link to Ascender docs domain. |
| docs/docsite/rst/common/images/ug-dashboard-top-nav.png | Updates/replaces binary screenshot asset. |
Comments suppressed due to low confidence (2)
docs/docsite/requirements.txt:46
docs/docsite/requirements.txtappears to be a pip-tools generated lockfile (seedocs/docsite/updater.sh), butsphinxis now unpinned. This makes doc builds non-reproducible and also suggests the file was edited by hand (pip-compile would normally pin versions). Updaterequirements.inas needed and regeneraterequirements.txtvia the updater script instead of committing an unpinned entry here.
snowballstemmer==3.0.1
# via sphinx
sphinx
# via
# -r requirements.in
# sphinx-ansible-theme
# sphinx-rtd-theme
# sphinxcontrib-jquery
sphinx-ansible-theme==0.10.4
docs/docsite/rst/contributor/report_issues.rst:16
- Several RST external links are missing a URL scheme (e.g.,
github.com/ctrliq/...). Sphinx will treat these as relative links, producing broken URLs in the rendered docs. Use fully qualified URLs likehttps://github.com/....
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
5
to
+7
| # Do not uncomment the line below. We need to be able to override the version via a file, and this | ||
| # causes the "version" key in setup.cfg to be ignored. | ||
| # [tool.setuptools_scm] | ||
| [tool.setuptools_scm] |
Comment on lines
+7
to
+13
| function switchVersionTo(slug) { | ||
| var current_url_path = window.location.pathname; | ||
| var url_version = current_url_path.search("/{{ current_version }}/") > -1 | ||
| ? "/{{ current_version }}/" | ||
| : "/latest/"; | ||
| var new_version_url = current_url_path.replace(url_version, "/" + slug + "/"); | ||
| window.location.replace(new_version_url); |
Comment on lines
+3
to
+7
| {%- set ascender_community_web = '<a href="https://docs.ansible.com/">Ascender Community</a>' %} | ||
| {#- Translators: the variable "sphinx_web" is a link to the Sphinx project documentation with the text "Sphinx" #} | ||
| {%- trans sphinx_web=sphinx_web %}Built with {{ sphinx_web }} using a{% endtrans %} | ||
| {#- Translators: "theme" refers to a theme for Sphinx, which alters the appearance of the generated documenation #} | ||
| <a href="https://sphinx-ansible-theme.rtfd.io">{% trans %}Sphinx Ansible Theme{% endtrans %}</a> |
| ---------------------- | ||
| --------------------------- | ||
|
|
||
| In order to use the GPG key for content singing and validation in Ascender, you must add it running the following command in the CLI: |
Comment on lines
+3
to
+7
| <div class="DocSite-globalNav ansibleNav"> | ||
| <ul> | ||
| <li><a href="https://ciq.com/blog/?search=&categories[0]=Ascender%20Pro&page=1&sortBy=date&sortDirection=desc" target="_blank">Blog</a></li> | ||
| <li><a href="https://github.com/ctrliq/ascender/discussions" target="_blank">Ascender Discussion Forum</a></li> | ||
| </ul> |
Comment on lines
+6
to
+8
| <a href="https://www.ansible.com/docs-left?utm_source=docs"> | ||
| <img style="border-width:0px;" src="https://cdn2.hubspot.net/hubfs/{{ theme_hubspot_id }}/docs-graphics/ASB-docs-left-rail.png" /> | ||
| </a> |
Comment on lines
+33
to
35
| - If you work in a part of the docs that is going through active development, your changes may be rejected, or you may be asked to `rebase`. A good idea before starting work is to have a discussion with us and ask questions on `Ascender Discussion Forum <https://github.com/ctrliq/ascender/discussions>`_. | ||
|
|
||
| - If you find an issue with the functions of the UI or API, please see the `Reporting Issues <github.com/ctrliq/ascender/blob/main/CONTRIBUTING.md#reporting-issues>`_ section to open an issue. |
Comment on lines
1
to
10
| export default function getDocsBaseUrl(config) { | ||
| let version = '4.5'; | ||
| const licenseType = config?.license_info?.license_type; | ||
|
|
||
| if (licenseType && licenseType !== 'open' && config?.version) { | ||
| version = parseFloat(config?.version.split('-')[0]).toFixed(1); | ||
| } | ||
|
|
||
| return `https://docs.ansible.com/automation-controller/${version}`; | ||
| return `https://docs.ascender-automation.org`; | ||
| // return `https://docs.ansible.com/automation-controller/${version}`; | ||
| } |
Comment on lines
73
to
76
| Access the Ascender user interface | ||
| ------------------------------ | ||
| ---------------------------------- | ||
|
|
||
| To access an instance of the Ascender interface, refer to `Build and run the development environment <github.com/ctrliq/ascender/blob/main/CONTRIBUTING.md#setting-up-your-development-environment>`_ for detail. Once you have your environment setup, you can access the Ascender UI by logging into it at `https://localhost:8043 <https://localhost:8043>`_, and access the API directly at `https://localhost:8043/api/ <https://localhost:8043/api/>`_. |
Comment on lines
+31
to
+35
| def get_html_theme_path(): | ||
| """Return list of HTML theme paths.""" | ||
| cur_dir = path.abspath(path.dirname(path.dirname(__file__))) | ||
| return cur_dir | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I am currently working on updating the documentation. It will be a long road, as there are lots of things to correct. But its a start.