🌐 Web query:

Sphinx pathto() function documentation relative path version

💡 Result:

In Sphinx HTML theme templates (Jinja), pathto() has two common “modes”:

• pathto(document): returns a URL (typically a relative link from the current page) to another built Sphinx document. [1] (sphinx-doc.org)
• pathto(file, 1) (i.e., pathto(file, True)): returns the path to a file that is relative to the root of the generated output (commonly used for static assets like _static/...). [1] (sphinx-doc.org)

This behavior is consistent across older Sphinx docs as well (e.g., 1.7.9 shows the same definitions). [2] (sphinx-hxl.readthedocs.io)

[1] https://www.sphinx-doc.org/en/master/development/html_themes/templating.html
[2] https://sphinx-hxl.readthedocs.io/en/stable/templating.html

Citations:

• 1: https://www.sphinx-doc.org/en/master/development/html_themes/templating.html
• 2: https://www.sphinx-doc.org/en/master/development/html_themes/templating.html
• 3: https://sphinx-hxl.readthedocs.io/en/stable/templating.html?utm_source=openai

🌐 Web query:

sphinx-multiversion how to link between versions recommended approach

💡 Result:

Recommended approach in sphinx-multiversion is to generate cross-version links at the template (Jinja) level, using the HTML-context helpers it provides—rather than hard-coding /vX.Y/… URLs.

1) Link to “the same page in another version” (best default)

Use vhasdoc() to check availability and vpathto() to compute the correct URL to the current page in another version (falling back to that version’s master_doc if the page doesn’t exist). (sphinx-contrib.github.io)

{# e.g. in a theme template like layout.html or a custom version switcher #}
{% if vhasdoc('v2.0.0') %}
  <a href="{{ vpathto('v2.0.0') }}">View this page in v2.0.0</a>
{% else %}
  <a href="{{ vpathto('v2.0.0') }}">Go to v2.0.0 docs</a>
{% endif %}

2) Build a version switcher (recommended UX)

Iterate versions and link with each version’s per-page item.url (this already points to “this page in that version”). (sphinx-contrib.github.io)

<ul>
  {% for item in versions %}
    <li><a href="{{ item.url }}">{{ item.name }}</a></li>
  {% endfor %}
</ul>

3) Link to “latest released” from anywhere

Use latest_version + vpathto(latest_version.name) to avoid hard-coding what “latest” is. (sphinx-contrib.github.io)

<a href="{{ vpathto(latest_version.name) }}">Latest docs ({{ latest_version.name }})</a>

When to use Intersphinx instead

If your “other versions” are actually built/published as separate doc sites (not via sphinx-multiversion’s single combined build), then treat each version as an external docs set and use sphinx.ext.intersphinx with separate inventories. (sphinx-doc.org)

Citations:

• 1: https://sphinx-contrib.github.io/multiversion/main/context.html
• 2: https://sphinx-contrib.github.io/multiversion/main/context.html
• 3: https://sphinx-contrib.github.io/multiversion/main/context.html
• 4: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html?utm_source=openai

🏁 Script executed:

# Check if there's sphinx configuration and multiversion setup
find . -name "conf.py" -o -name "*.py" | head -20
git ls-files | grep -E "(conf\.py|setup\.py|requirements)" | head -10

Repository: oceanbase/pyseekdb

Length of output: 748

🏁 Script executed:

# Search for other version templates or multiversion config
find docs -type f -name "*.html" -o -name "*.cfg" | grep -E "(version|multiversion)" | head -20

Repository: oceanbase/pyseekdb

Length of output: 98

🏁 Script executed:

# Check docs/conf.py for sphinx-multiversion configuration
cat docs/conf.py | head -100

Repository: oceanbase/pyseekdb

Length of output: 1913

🏁 Script executed:

# Look for any multiversion configuration or extensions
grep -r "multiversion\|vpathto\|vhasdoc" docs/ --include="*.py" --include="*.html" 2>/dev/null || echo "No multiversion patterns found"

Repository: oceanbase/pyseekdb

Length of output: 150

🏁 Script executed:

# Check if there are other templates using pathto or version awareness
find docs/_templates -type f -name "*.html" -exec basename {} \; 2>/dev/null

Repository: oceanbase/pyseekdb

Length of output: 94

🏁 Script executed:

# Look at the version_warning.html more carefully and surrounding context
cat -n docs/_templates/version_warning.html

Repository: oceanbase/pyseekdb

Length of output: 400