Getting the base URL

[Carl Gay]

My project has some external HTML files that are put in place as a separate build step and I would like to add a link to them in my toctree. Currently I have this, and it works fine, but it assumes a static URL and therefore when testing the site on another host/port the URLs are incorrect...

.. toctree::
   :caption: Reference
   :hidden:

   Dylan Reference Manual <https://opendylan.org/books/drm/>
   Package Docs <package/index>
   Open Dylan Libraries <library-reference/index>
   All Documentation <documentation/index>
   Full Index <genindex>

So instead of <https://opendylan.org/books/drm/> I would like to use something like <${base-url}/books/drm/> where the current base URL is substituted.

Simply using </books/drm/> doesn't work; I get "WARNING: toctree contains reference to nonexisting document 'books/drm'" and the link is omitted from the output.

As always, I feel like I'm missing something obvious.  Is there a way to do this?

Thanks.

[Steevie]

Hi Carl,

I am not sure I understood your use case, so my solution might not be
useful.

First of all: in a toctree you can not use replacement or roles, so your
approach can not work. Therefore, I think the simplest solution is to
wrap
the entire toctree in an only:: directive, e.g.,

.. only:: main

.. toctree::
:caption: Reference
:hidden:

Dylan Reference Manual <https://opendylan.org/books/drm/>
Package Docs <package/index>
Open Dylan Libraries <library-reference/index>
All Documentation <documentation/index>
Full Index <genindex>

Then you duplicate this block, changing "main" to something else
("dylan"), and the URL to the one you want to test (https://otherurl.org/
books/drm/)

At build time, you pass a -t main or -t dylan option to build the one you
want, e.g., sphinx-build -t dylan -b html source build

If you use make, you can define two Makefiles and add the -t main/dylan
to
the SPHINXOPTS of either Makefile, then pass the correct file to make
(make -f Makefile vs. make -f -Makefile-dylan)

HTH,
Stefano

[Carl Gay]

Hi Stefano, thanks for the reply. If I understand your solution correctly, it requires duplicating the toctree for each distinct URL. What I want is that if any member of the team builds/runs the site on their local machine the URL will be correct for their machine. Specifically, if I access the site as https://localhost:8001/ then the link should take me to https://localhost:8001/books/drm/ and if I access the live site as https://opendylan.org/ the link should take me to https://opendylan.org/books/drm/.

So I think I could use your suggestion, with -t main and -t localhost, but only if I require testing to be done on the same port number (e.g., 8001 above).

The syntax for toctree entries is Title <target>, where target is either an rST document pathname or (apparently) a fully specified URL. What I really want is a way to specify a relative URL there, but I can see how that would be difficult to distinguish from a relative file path without adding special syntax.  (e.g., Title <url:/books/drm/>)

This isn't a big problem, I just thought maybe there was a simple way to specify a relative URL there that I had overlooked. So rather than duplicating the toctree and adding special flags for the build I'll probably just live with it the way it is.

Thanks.

-Carl

[Steevie]

Hi Carl,

On Tue, 7 May 2024 09:24:33 -0700 (PDT), Carl Gay wrote:

> Hi Stefano, thanks for the reply. If I understand your solution
> correctly, it requires duplicating the toctree for each distinct URL.
> What I want is that if any member of the team builds/runs the site on
> their local machine the URL will be correct for their machine.
> Specifically, if I access the site as https://localhost:8001/ then the
> link should take me to https://localhost:8001/books/drm/ and if I access
> the live site as https://opendylan.org/ the link should take me to
> https://opendylan.org/books/drm/.

Well, then I think I got it right. If the "problem" is that every
developer has its own setup, you could just put the index.rst
in .gitignore, so the official doc features the opendylan URL and
everyone
can test it locally with its preferred URL.

I just thought of another possibility, perhaps more maintainable: instead
of changing the URL in the toctree, you replace the toctree line

Dylan Reference Manual <https://opendylan.org/books/drm/>

with the name of an actual file (let's call it drm.rst)

with the content of that file being

========================
Dylan Reference Manual
========================

.. raw:: html

<html>
<head>
<meta http-equiv="refresh" content="0; url=http://localhost:8020/
books/drm">
</head>
<body>
</body>
</html>

(in the 'official' documentation you have url=https://opendylan.org/books/
drm/)

In this way the effect is exactly the same of having the URL in the
toctree, but every developer can change the file at will (again, putting
the drm.rst file in .gitignore allows on the one side every developer to
change it at will and on the other one prevents pushing it by mistake).

HTH,
Stefano