Splitting HTML pages

[Jean Abou Samra]

Hi,

Apologies if I've missed it somewhere in the documentation
or the issue tracker, but I can't find an answer to this.

Suppose I have a set of documentation files each containing
a chapter made of many sections. It can be more convenient
to keep them in a single file so it is easier to restructure
the content. The downside is that this file is rendered to
one single HTML page, which can be overwhelming for the reader
and/or slow to load, particularly if there are many images,
as in my use case. I'd prefer to have one HTML page per section.
Is this possible, possibly in an extension? If I had to
code it, where could I start?

Thanks,
Jean

[Matt Documatt]

Hello Jean,
I don't know about any extension doing this. A "unit of size" in Sphinx is .rst file (a document). There are three builtin HTML builders

- "html" makes one HTML for one document
- "dirhtml" creates docname/index.html from docname.rst to prettier URLs ("docs.foo.com/getting-started" instead of "docs.foo.com/getting-started.html")
- "singlehtml" creates one big long HTML from all documents

(https://www.sphinx-doc.org/en/master/usage/builders/index.html)

In other words, I would recommend creating shorter .rst documents.

--
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/74d9be92-873e-fcc1-9da6-6248bd8cb44f%40abou-samra.fr.

[Slavko]

Ahoj,

Dňa Thu, 10 Feb 2022 10:31:47 +0100 Matt Documatt <ma...@documatt.com>
napísal:

> Hello Jean,
> I don't know about any extension doing this. A "unit of size" in
> Sphinx is .rst file (a document). There are three builtin HTML
> builders
>
> - "html" makes one HTML for one document
> - "dirhtml" creates docname/index.html from docname.rst to prettier
> URLs ("docs.foo.com/getting-started" instead of
> "docs.foo.com/getting-started.html")
> - "singlehtml" creates one big long HTML from all documents

I am using sphinx to build multiple HTML only projects, i use this
structure of .rst files, eg.:

500_baliky/
├── index.rst
├── 110_lede-sdk.rst
└── 210_lede-imagebuild.rst

And i am including documents in toctree by this (where appropriate -- in
index.rst only):

.. toctree::
:titlesonly:
:glob:

*
*/index

+ the "*" item includes .rst files in current dir
+ the "*/index" allow me to include nested subdirs (if needed)

This allow me to split things into "small" files, which respects
directory structure and creates nested toctrees. Using "index.rst"
results, that even webserver opens right index file, when directory is
accessed. I use this from time of 1.5 version eg. for my notes, which
counts more than 1500 pages and produces nice results.

That structure looks ugly in PDF, at least it did when i test it years
ago, thus i do not suggest it in case when PDF is needed.

regards

--
Slavko
https://www.slavino.sk

[Jean Abou Samra]

Hi,

Thank you both for your replies. I know that the standard is to
make one .rst file per HTML page, but here is some context on why
I would prefer splitting at sections. The manuals I am musing
about converting to Sphinx (from Texinfo with a Python preprocessor
and a fragile and horrifyingly complicated build system) are here:

https://lilypond.org/doc/v2.23/Documentation/web/manuals.html

with the main one being:

https://lilypond.org/doc/v2.23/Documentation/notation/index.html

As you can see, there is basically an image after every paragraph
in most sections. I don't have a slow Internet connection or
a poor browser to test, and maybe this is paranoid, but I fear
pages are going to be too slow to load for some people if I
keep the current structure which is generally one file per section,
whereas there is an HTML page for each subsection. As a data point,
you can visit

https://lilypond.org/doc/v2.23/Documentation/notation-big-page

which is the single-page HTML and takes some long seconds to load
for me.

Also, this is a mature piece of software, people are used to this
documentation. I would prefer not to change its feel change too much,
and keeping the current structure would mean making 145 files
for Sphinx whereas there are 25 in Texinfo -- I at least find
the latter more convenient for editing.

So I guess I will have to plunge into the internals of HTML
builders.

Best regards,
Jean

[Slavko]

Ahoj,

Dňa Fri, 11 Feb 2022 18:15:56 +0100 Jean Abou Samra
<je...@abou-samra.fr> napísal:

> Also, this is a mature piece of software, people are used to this
> documentation. I would prefer not to change its feel change too much,
> and keeping the current structure would mean making 145 files
> for Sphinx whereas there are 25 in Texinfo -- I at least find
> the latter more convenient for editing.

If it is convenient or not depends on tools ;-)

I have link on any page, which directly opens underlying .rst file in my
editor (and small daemon which rebuild docs on file change). But that
will require something more specific for you, as you will do not want
these links on production page, while i do not care about this.

Perhaps some optional variable/option can help with distinguishing devel
and public builds, but this is out of my knowledge.

BTW, nice images (i am not musician).

[Matthias Geier]

Hi Jean.

If it's only about slow loading of many images, maybe adding the
loading=lazy attribute to <img> tags would help?

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading

I don't think that's available in Sphinx out-of-the-box, but maybe an
extension could be created to enable this?

I could also imagine a Sphinx option html_img_lazy_loading (or
something like that).

Note that a :loading: option has already been suggested:
https://github.com/sphinx-doc/sphinx/issues/6706

cheers,
Matthias