:doc: and other html documents

[Daniele Zambelli]

Hi Sphinx Users!

I'm using Sphinx to build a site that allows you to view html pages
produced with tools other than Sphinx.

I have placed these documents as a subdirectory of _static.

In config.py I have the following line:

html_static_path = ['_static',]

In source I have the following directory tree:
...
└── source
├── ...
├── 04link.rst
├── conf.py
├── img
│ ├── ...
├── index.rst
├── _static
│ └── mypages
│ └── provaesp
│ ├── provaesp.css
│ └── provaesp.html
└── _templates
...

and in the file "04link.rst" the instruction:

:doc:`Html with an expression <_static/mypages/provaesp/provaesp>`.

In compilation I get:
...
/.../source/04link.rst:65: WARNING: unknown document:
_static/mypages/provaesp/provaesp
...

In the produced html file I don't get the link to the provesp.html file.

Where am I wrong?

Thanks for your attention.

--

Daniele

www.fugamatematica.blogspot.com

giusto!
nel verso
forse è perché non guardiamo le cose
Quando non ci capiamo,

[Matt Documatt]

Hello Daniele,
you misunderstand what html_static_path and :doc: are doing.

html_static_path is intentioned for files like styles, fonts, icons. During the build, files end up in _static/. Usually, a HTML theme expects its resources here (e.g. <link rel="stylesheet" type="text/css" href="../_static/mytheme.css">)

:doc: is for creating links to Sphinx documents (files that are processed and built). The path is without the file extension. E.g., :doc:`installing/windows` will be a link to installing/windows.rst.

For the purposes, you ask, more suitable is html_extra_path (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path). It copies extra paths to the output root.

1. Add

html_extra_path = ["_pages"]

to conf.py

2. Create _pages/ in the root (where is conf.py)

3. Create my.html here.

4. In any Sphinx document, use hyperlink reference (https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases), e.g.

See `extra document <my.html>`_.

--
Matt
https://techwriter.documatt.com

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAE512rMKhpvs9-a7L1qep74MJqE1JxmTnh%3DezN4pVyf61Aww3w%40mail.gmail.com.

[Daniele Zambelli]

Il giorno mar 21 dic 2021 alle ore 10:02 Matt Documatt
<ma...@documatt.com> ha scritto:

>
> Hello Daniele,
> you misunderstand what html_static_path and :doc: are doing.

> [...]

Thanks for the very quick and competent reply that clarified how to
solve the problem.

Now the links to the html pages work fine.

Thank you very much.