:doc: and other html documents

Skip to first unread message

Daniele Zambelli

Dec 21, 2021, 3:11:26 AM12/21/21
to sphinx...@googlegroups.com
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:

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

Where am I wrong?

Thanks for your attention.




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

Matt Documatt

Dec 21, 2021, 4:02:06 AM12/21/21
to sphinx...@googlegroups.com
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>`_.

> --
> 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

Dec 21, 2021, 9:24:05 AM12/21/21
to sphinx...@googlegroups.com
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.
Reply all
Reply to author
0 new messages