Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@xxxxxxx>:
> On Sat, 13 Aug 2016 16:12:42 +0200
> Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
>
>> Add a generic way to build only a reST sub-folder with or
>> without a individual *build-theme*.
>>
>> * control *sub-folders* by environment SPHINXDIRS
>> * control *build-theme* by environment SPHINX_CONF
>>
>> Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
>> can be build and distributed *stand-alone*. E.g. to compile only the
>> html of 'media' and 'gpu' folder use::
>>
>> make SPHINXDIRS="media gpu" htmldocs
>>
>> To use an additional sphinx-build configuration (*build-theme*) set the
>> name of the configuration file to SPHINX_CONF. E.g. to compile only the
>> html of 'media' with the *nit-picking* build use::
>>
>> make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs
>>
>> With this, the Documentation/conf.py is read first and updated with the
>> configuration values from the Documentation/media/conf_nitpick.py.
>
> So this patch appears to have had the undocumented effect of moving HTML
> output from Documentation/output/html to Documentation/output. I am
> assuming that was not the intended result?
Sorry for being unclear. My intention was to produce a structured output
which could copied 1:1 to a static HTML server.
Since the documentation says:
"The generated documentation is placed in ``Documentation/output``."
I thought I'am free to give it a structure. But I haven't clarified
this point / sorry.
The main structure is, that a HTML output is produced without any
folder prefix, so a simple htmldoc target goes to::
Documentation/output/index.html
Other formats like epub are placed into a format-specific subfolder e.g.
the epub from target "epubdocs" are placed in::
Documentation/output/epub/*
If you only compile a subfolder e.g. "SPHINXDIRS=media" you get a
the analogous structure in the Documentation/output/media folder::
Documentation/output/{subfolder}/{non-html-format}/
With you can place the Documentation/output/{subfolder} on
your HTTP server including all formats.
Unfortunately at the this time,
* the pdf goes to the "latex" folder .. since this is WIP
and there are different solutions conceivable ... I left
it open for the first.
* in the index.html we miss some links to pdf-/man- etc files
The last point needs some discussion. Hopefully, this discussion
starts right here.
> I'm not sure that we actually need the format-specific subfolders, but we
> should be consistent across all the formats and in the documentation and,
> as of this patch, we're not.
IMHO a structure where only non-HTML formats are placed in subfolders
(described above) is the better choice.
In the long run I like to get rid of all the intermediate formats
(latex, .doctrees) and build a clear output-folder (with all formats
in) which could be copied 1:1 to a static HTTP-server.
-- Markus --
> jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
