docs: improve PyFluent docs discoverability - #5355
Conversation
github-actions
Bot
added
documentation
Up to standards ✅🟢 Issues
|
There was a problem hiding this comment.
Pull request overview
Improves PyFluent documentation discoverability through canonical URLs, sitemap generation, and an HTML cheat sheet.
Changes:
- Adds sitemap and canonical URL configuration.
- Publishes and links an HTML cheat sheet.
- Adds the required documentation dependency and changelog entry.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
pyproject.toml |
Adds sphinx-sitemap. |
doc/source/conf.py |
Configures sitemap and canonical URLs. |
doc/source/_templates/layout.html |
Adds canonical metadata. |
doc/source/cheatsheet/index.rst |
Introduces the HTML cheat sheet. |
doc/source/index.rst |
Links the cheat sheet. |
doc/changelog.d/5355.documentation.md |
Records the documentation change. |
Suppressed comments (7)
doc/source/cheatsheet/index.rst:104
- This rebinds
turbulenceto the string constant instead of updatingturbulence_specification; the next access toturbulence.turbulent_intensitythen fails becauseturbulenceis no longer the settings object. Assign the constant to the setting property.
turbulence = (
turbulence.turbulence_specification.INTENSITY_AND_HYDRAULIC_DIAMETER
)
doc/source/cheatsheet/index.rst:149
- Assigning the enum value to the local
k_epsilon_modelvariable does not change the Fluent setting, so the model remains at its previous/default variant. Assign it back throughviscous.k_epsilon_model.
k_epsilon_model = viscous.k_epsilon_model
k_epsilon_model = k_epsilon_model.REALIZABLE
doc/source/cheatsheet/index.rst:156
- This only replaces the local
speciesvariable with a string constant; it never enables species transport in Fluent. Keep the settings object and assign itsmodel.optionproperty.
species = Species(solver).model.option
species = species.SPECIES_TRANSPORT
doc/source/cheatsheet/index.rst:172
- Reassigning
grad_schemechanges only the local variable and leaves the solver's gradient scheme unchanged. The value must be assigned to the settings property.
grad_scheme = methods.spatial_discretization.gradient_scheme
grad_scheme = grad_scheme.GREEN_GAUSS_NODE_BASED
doc/source/cheatsheet/index.rst:182
- The second assignment only rebinds a local variable, so the newly created report definition never receives a report type. Assign the value to the definition's
report_typeproperty.
soln_report_type = rep_defs.surface["outlet-temp-avg"].report_type
soln_report_type = soln_report_type.SURFACE_AREA
doc/source/cheatsheet/index.rst:192
- This rebinds
init_typewithout updatinginitialization.initialization_type, so the documented workflow does not select hybrid initialization. Assign the enum value to the setting property.
init_type = initialization.initialization_type
init_type = init_type.HYBRID
doc/source/cheatsheet/index.rst:83
- Changing
setup_typedoes not itself rebuild the Describe Geometry task's children. The workflow API requiresupdate_child_tasksbefore reading/setting this argument and again after the value changes (as used indoc/source/user_guide/meshing/new_meshing_workflows.rst:62-66); otherwise the downstream watertight tasks can retain the wrong structure before volume meshing.
watertight.describe_geometry.setup_type = "fluid"
watertight.describe_geometry()
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| .. code-block:: python | ||
|
|
||
| session = pyfluent.Solver.from_connection(ip, port, password) |
| # Canonical base URL used by sphinx-sitemap and by search engines to | ||
| # consolidate ranking signal onto the `stable` version of the docs. | ||
| # See pyfluent-doc-plan.md §4 and §5. | ||
| html_baseurl = "https://fluent.docs.pyansys.com/version/stable/" |
| {% block extrahead %} | ||
| {{ super() }} | ||
| {%- if pagename %} | ||
| <link rel="canonical" | ||
| href="https://fluent.docs.pyansys.com/version/stable/{{ pagename }}.html" /> |
|
I checked 7-8 PyAnsys repos and the pattern holds consistently: in every case I checked, the official docs are severely outranked in search results. As you know, PyAnsys docs are properly maintained, peer-reviewed and up to date. I hope that the kind of changes in this branch and additional comments in the description will contribute to an improvement (as noted in the description, the changes are AI-generated) that could be shared across repos. It's possible a few repos have already addressed this independently and if any team has tackled it separately, it'd be worth comparing notes so we're not duplicating effort. Separately: the Ansys forum consistently ranks above the official docs in these searches, despite that content being older, apaprently unmaintained, and not held to the same review process as our docs. Readers landing on it have no way of knowing that. I'd flag this as worth addressing. |
|
Hi @seanpearsonuk thanks for bringing this to our attention! We have seen a decay in the ranking of our docs indeed, but @jorgepiloto has been investigating this issue and it is mostly related to a Google Console account subscription being required to rank higher in the SEO algorithms. In fact, some of the operations being performed in this PR such as the sitemap.xml generation, is also done by the doc publishing actions. Nonetheless, the canonicalization logic seems pretty interesting and reusable! Maybe we could move this to the Sphinx theme directly @jorgepiloto? Regarding the cheat sheet being available as HTML - that is also an option for projects to have. However we are not enforcing teams to provide it in HTML for now. Worth looking into though - maybe we could find a way to have a single source of truth for the cheat sheet (either the |
|
Hi @seanpearsonuk, thanks for opening this. We just noticed the same. Our deploy actions should take care of sitemap generation and canonical links injection. This is because these actions have access to the full website, whereas Sphinx extensions do not conceive multi-version documentation. My suspicions go in the path of Google classifying our pages as AI-generated due to the amount of duplicated content across versions. |
docs: improve PyFluent docs discoverability (SEO)
AI generated PR / WIP
Background
Searching for "PyFluent" and related terms (e.g. "PyFluent cheat sheet",
"PyFluent settings API") currently surfaces the Ansys Developer forum
(
developer.ansys.com/developer.synopsys.com) ahead of the officialPyAnsys documentation, and in some cases the official docs don't appear at
all in the first several pages of results. Forum content is unmaintained
and can be materially out of date compared to the maintained docs.
Investigation confirmed this is not a
robots.txtblock or ade-indexing problem —
fluent.docs.pyansys.comand its cheat sheet PDFare indexed and do appear in search. The root causes are ranking-signal
problems that are fixable independent of Ansys's overall domain authority:
three separate URLs (
fluent.docs.pyansys.com/version/stable/_static/cheat_sheet.pdf,fluent.docs.pyansys.com/version/dev/_static/cheat_sheet.pdf, andcheatsheets.docs.pyansys.com/pyfluent_cheat_sheet.pdf), splittingranking signal three ways instead of consolidating it onto one URL.
competing forum page is a normal HTML blog post with real headings and
anchor links, which Google generally indexes and ranks better for
phrase-based queries than PDF text.
PyFluent (
/version/0.14/,/version/0.34.dev0/,/version/dev/,/version/stable/, etc.) is a near-duplicate page with no canonicaltag pointing back to one authoritative URL, further diluting ranking
signal for any single page.
Ansys Developer forum back to the canonical PyAnsys docs, despite the
forum content covering the same library.
sitemap.xmlpresence/submission andGoogle Search Console coverage status had not been confirmed for
fluent.docs.pyansys.com.This PR applies the fixes for the ranking-signal problems that can be
addressed inside this repository. The remaining items (hosting-side
redirects, Google Search Console work, forum backlink request) still need
to be actioned outside the repo; they are called out below.
Root causes addressed
doc/source/cheatsheet/index.rstconf.py+_templates/layout.htmlsphinx-sitemapaddedChanges
1. Canonicalize every versioned docs page to
stabledoc/source/conf.py— sethtml_baseurl = "https://fluent.docs.pyansys.com/version/stable/"andsitemap_url_scheme = "{link}".doc/source/_templates/layout.html(new) — extends theansys-sphinx-theme base template and injects
<link rel="canonical" href=".../version/stable/{{ pagename }}.html">inextraheadon every page.This tells Google that
/version/0.14/…,/version/dev/…,/version/0.34.dev0/…etc. all consolidate onto thestableequivalent —directly addressing root cause #3 (ranking signal split across every
released version).
2. Generate a real
sitemap.xmlpyproject.toml— addedsphinx-sitemap==2.6.0to thedocdependency set.
doc/source/conf.py— registeredsphinx_sitemapinextensions.sitemap.xmlwill now be produced automatically on every doc build,enabling submission via Google Search Console.
3. Publish the cheat sheet as a real HTML page
doc/source/cheatsheet/index.rst(new) — HTML cheat sheet with:_ref_pyfluent_cheat_sheetfor internal linking.launching Ansys Fluent from Python, importing a mesh,
defining materials, defining boundary conditions,
modifying cell zone conditions, applying solution settings,
accessing field data.
.. contents::block giving Google real anchor targets for eachsection — the "quick reference" jump-link UX pattern that is one
reason the forum post currently wins.
<h2>/<h3>headings mirroring the Quarto cheat sheet content:Quick start, Launching Fluent, Reading and writing case and data files,
Importing a mesh, Defining boundary conditions, Defining materials,
Modifying cell zone conditions, Enabling physics models, Applying
solution settings, Accessing field data, Reduction functions,
Solution variables.
doc/source/cheatsheet/cheat_sheet.qmdso the two are content-equivalent at merge time.
doc/source/index.rst:cheatsheet/indexto the hidden toctree.literal anchor text "PyFluent cheat sheet".
Not in this PR (out-of-repo follow-ups)
These items cannot be done in this repository and remain open:
fluent.docs.pyansys.com/version/{stable,dev}/_static/cheat_sheet.pdfstill need to be 301'd (or stubbed with meta-refresh + canonical) to
cheatsheets.docs.pyansys.com/pyfluent_cheat_sheet.pdf. Requireshosting/CI access. Recommended canonical location is
cheatsheets.docs.pyansys.comsince it acts as the shared hub acrossPyAnsys libraries.
fluent.docs.pyansys.com, submit thenewly generated
sitemap.xml, and request re-indexing of the canonicalcheat sheet URL and a sample of
stablepages. Check the Coverage /Page indexing report for the cheat sheet PDF URLs, looking for
"Duplicate, Google chose different canonical" warnings clearing.
robots.txt. Add aSitemap:line pointing at the generatedsitemap.xml. Lives at the hosting root, not in Sphinx source.to have the existing PyFluent cheat sheet and settings-API posts link
to the canonical PyAnsys docs as the maintained source of truth.
fragmentation issue as the cheat sheet.
other docs pages) to point at the new canonical cheat sheet URL
directly, rather than relying on redirects.
Caveats and risks
stable.html_baseurland theinjected canonical
<link>are set unconditionally to thestableURL. On
dev-only pages that don't yet exist instable, this willcanonicalize to a non-existent URL until the next release. If Search
Console flags this, drive
html_baseurland the canonical URL from aCI env var so only
stable/tagged builds inject a cross-versioncanonical and
devself-canonicalizes.is one source generating both the PDF and the HTML. This PR copies the
content from
cheat_sheet.qmdinto a new.rstrather thangenerating both from one source. Content drift risk is real; a
follow-up issue to unify the source is recommended.
passes in CI before merge.
Verification
Post-deploy verification enabled by this PR:
<link>pointing at the equivalent
stableURL.sitemap.xmlshould be present at the site root after deploy.site:fluent.docs.pyansys.com "PyFluent cheat sheet"should, afterre-crawl (typically 1–4 weeks), start surfacing the new HTML page
rather than only the PDF. Ranking changes from canonicalization and
redirects take days to a few weeks to appear; do not judge success
from same-day search checks.
duplicate/canonical conflicts for the cheat sheet URLs once the
hosting-side redirects (see "Not in this PR") are also live.
Files changed
doc/source/conf.py— canonical base URL + sitemap extension.doc/source/_templates/layout.html— new, canonical link injection.doc/source/cheatsheet/index.rst— new, HTML cheat sheet.doc/source/index.rst— toctree entry + homepage link.pyproject.toml—sphinx-sitemapdependency.