| Message ID | 1471097568-25990-2-git-send-email-markus.heiser@darmarit.de (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Sat, 13 Aug 2016 16:12:42 +0200 Markus Heiser <markus.heiser@darmarit.de> 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? 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. jon -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>: > On Sat, 13 Aug 2016 16:12:42 +0200 > Markus Heiser <markus.heiser@darmarit.de> 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-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: > Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>: > * the pdf goes to the "latex" folder .. since this is WIP > and there are different solutions conceivable ... I left > it open for the first. Mea culpa. As I said, I intended my patches as RFC only. > > * 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. When I added the Documentation/output subfolder, my main intention was to separate the source documents from everything that is generated, intermediate or final. I suggest you keep the generated files somewhere under output. This'll be handly also when ensuring O= works. I set up the format specific subfolders, because I thought people would want to keep them separated and independent. For me, all the formats were equal and at the same level in that regard. You're suggesting to make html the root of everything? BR, Jani.
Em Thu, 18 Aug 2016 16:35:14 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Sat, 13 Aug 2016 16:12:42 +0200 > Markus Heiser <markus.heiser@darmarit.de> 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? > > 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. Agreed. it should either use subfolders or not. IMHO, the best would be to just output everything at Documentation/output, if this is possible. That "fixes" the issue of generating PDF files at the latex dir, with sounds weird, IMHO. I guess I mention on a previous e-mail, but SPHINXDIRS= is not working for PDF files generation. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>: > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>: >> * the pdf goes to the "latex" folder .. since this is WIP >> and there are different solutions conceivable ... I left >> it open for the first. > > Mea culpa. As I said, I intended my patches as RFC only. I think this is OK for the first. I thought that we first let finish Mauro's task on making the media PDF and after this we decide how move from the latex folder to a pdf folder (one solution see below). >>> 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. > > When I added the Documentation/output subfolder, my main intention was > to separate the source documents from everything that is generated, > intermediate or final. I suggest you keep the generated files somewhere > under output. This'll be handly also when ensuring O= works. Yes, everything is under output / tested O=.. > I set up the format specific subfolders, because I thought people would > want to keep them separated and independent. For me, all the formats > were equal and at the same level in that regard. You're suggesting to > make html the root of everything? Yes this was my intention. With some additional work, we can build a root index.html where the other formats are linked. Since other formats *below* index.html, everything is *reachable* from the root index.html. Am 19.08.2016 um 15:32 schrieb Mauro Carvalho Chehab <mchehab@infradead.org>: > > Agreed. it should either use subfolders or not. > > IMHO, the best would be to just output everything at > Documentation/output, if this is possible. That "fixes" the issue > of generating PDF files at the latex dir, with sounds weird, IMHO. Changing the latex/pdf issue should be just a two-liner (not yet tested). @@ -71,8 +71,8 @@ ifeq ($(HAVE_PDFLATEX),0) $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX - @$(call loop_cmd,sphinx,latex,.,latex,.) - $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex + @$(call loop_cmd,sphinx,latex,.,pdf,.) + $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/pdf endif # HAVE_PDFLATEX > I guess I mention on a previous e-mail, but SPHINXDIRS= is not working > for PDF files generation. Not yet, there is a concurrency question to answer, should sub-folder's PDFs defined in the main conf.py-file or in the sub-folder conf.py? I suggest the last one, or in other words: the PDF content of a target should have the same content as the HTML target even if it is a subfolder or the whole documentation. But this is only possible if we know, that all media content can be integrated in the big PDF file. After said this, what is your suggestion? For me its all equal, these are only my 2cent to this discussion :-) -- Markus -- > > Thanks, > Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Fri, 19 Aug 2016 17:52:07 +0200 Markus Heiser <markus.heiser@darmarit.de> escreveu: > Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>: > > > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: > >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>: > >> * the pdf goes to the "latex" folder .. since this is WIP > >> and there are different solutions conceivable ... I left > >> it open for the first. > > > > Mea culpa. As I said, I intended my patches as RFC only. > > I think this is OK for the first. I thought that we first > let finish Mauro's task on making the media PDF and after > this we decide how move from the latex folder to a pdf folder > (one solution see below). Most of the work is done: the uAPI book. The other books don't use much tables. So, I guess it should be easier to fix them. I'll look on the other media books next week. > > >>> 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. > > > > When I added the Documentation/output subfolder, my main intention was > > to separate the source documents from everything that is generated, > > intermediate or final. I suggest you keep the generated files somewhere > > under output. This'll be handly also when ensuring O= works. > > Yes, everything is under output / tested O=.. > > > I set up the format specific subfolders, because I thought people would > > want to keep them separated and independent. For me, all the formats > > were equal and at the same level in that regard. You're suggesting to > > make html the root of everything? > > Yes this was my intention. With some additional work, we can build a > root index.html where the other formats are linked. Since other > formats *below* index.html, everything is *reachable* from the root > index.html. > > Am 19.08.2016 um 15:32 schrieb Mauro Carvalho Chehab <mchehab@infradead.org>: > > > > Agreed. it should either use subfolders or not. > > > > IMHO, the best would be to just output everything at > > Documentation/output, if this is possible. That "fixes" the issue > > of generating PDF files at the latex dir, with sounds weird, IMHO. > > Changing the latex/pdf issue should be just a two-liner (not yet tested). > > @@ -71,8 +71,8 @@ ifeq ($(HAVE_PDFLATEX),0) > $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) > @echo " SKIP Sphinx $@ target." > else # HAVE_PDFLATEX > - @$(call loop_cmd,sphinx,latex,.,latex,.) > - $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex > + @$(call loop_cmd,sphinx,latex,.,pdf,.) > + $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/pdf > endif # HAVE_PDFLATEX True, but I would still prefer to place everything at $(BUILDDIR), but this is just my personal preference. Not really against per-format subdir. > > > > I guess I mention on a previous e-mail, but SPHINXDIRS= is not working > > for PDF files generation. > > Not yet, there is a concurrency question to answer, should sub-folder's > PDFs defined in the main conf.py-file or in the sub-folder conf.py? > > I suggest the last one, or in other words: the PDF content of a target > should have the same content as the HTML target even if it is a subfolder > or the whole documentation. But this is only possible if we know, that > all media content can be integrated in the big PDF file. It can. However, in practice, experienced developers use only the uAPI book most of the time. So, splitting the media documentation on 4 books IMHO makes sense. Yet, the all-in-one media book has only ~3MB. Not big. https://mchehab.fedorapeople.org/media.pdf > > After said this, what is your suggestion? For me its all equal, these > are only my 2cent to this discussion :-) > > -- Markus -- > > > > > Thanks, > > Mauro Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Fri, 19 Aug 2016 17:40:38 -0300 Mauro Carvalho Chehab <mchehab@infradead.org> escreveu: > Em Fri, 19 Aug 2016 17:52:07 +0200 > Markus Heiser <markus.heiser@darmarit.de> escreveu: > > > After said this, what is your suggestion? For me its all equal, these > > are only my 2cent to this discussion :-) Forgot to mention, but I noticed that, sometimes, the building system doesn't get the cross-references right, and produces a PDF file (or an HTML file) with no TOC tables. The output files are still generated. I didn't try to track the root case. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Fri, 19 Aug 2016 17:52:07 +0200 Markus Heiser <markus.heiser@darmarit.de> escreveu: > Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>: > > > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: > >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>: > >> * the pdf goes to the "latex" folder .. since this is WIP > >> and there are different solutions conceivable ... I left > >> it open for the first. > > > > Mea culpa. As I said, I intended my patches as RFC only. > > I think this is OK for the first. I thought that we first > let finish Mauro's task on making the media PDF and after > this we decide how move from the latex folder to a pdf folder > (one solution see below). Finished handling all tables. I'm sending the last 2 patches right now. Now, all tables fit into the page margins. Yet, I suspect that flat-table extension causes some troubles when cspan is used for LaTeX. It would be good if Markus could double check them. There are just two things that won't fit at the margins of the document: 1) included files with long lines. We might put those includes into a begingroup and use a smaller font, but IMHO the best is to fix the few cases on them, as those lines are very likely violating the 80 column limit; 2) kernel-doc output for big arguments. We have lots of function argument inside several media structs, like at: struct v4l2_subdev_core_ops. one of such arguments is this function: int (* s_io_pin_config) (struct v4l2_subdev *sd, size_t n,struct v4l2_subdev_io_pin_config *pincfg); When kernel-doc generates the Members description, as the above line is bigger than 80 columns, it simply truncates its description to: Members int (*)(struct v4l2_subdev *sd) log_status callback for VIDIOC_LOG_STATUS ioctl handler code. int (*)(struct v4l2_subdev *sd,size_t n,struct v4l2_subdev_io_pin_config *pincfg) s_io_pin_con ... The LaTeX output for it is: \textbf{Members} \begin{description} \item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd) log\_status}}] \leavevmode callback for \sphinxcode{VIDIOC\_LOG\_STATUS} ioctl handler code. \item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd, size\_t n,struct v4l2\_subdev\_io\_pin\_config *pincfg) s\_io\_pin\_config}}] \leavevmode configure one or more chip I/O pins for chips that multiplex different internal signal pads out to IO pins. This function takes a pointer to an array of `n' pin configuration entries, one for each pin being configured. This function could be called at times other than just subdevice initialization. It seems that \sphinxcode{} doesn't allow line breaks. Maybe we can override it via conf.py. I'll play with it and see if I can find a solution. Yet, this could have side effects on other places. Any suggestions about how to fix it? PS.: if you want to see, it is at: https://mchehab.fedorapeople.org/media.pdf on page 623. There is one additional issue on LaTeX output: it numbered the document on a very different way than on html. Also, it has just one TOC. This is very bad, because, as we had to manually numerate figures, their number/names look weird on LaTeX output. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Sat, 20 Aug 2016 09:51:57 -0300 Mauro Carvalho Chehab <mchehab@infradead.org> escreveu: > Em Fri, 19 Aug 2016 17:52:07 +0200 > Markus Heiser <markus.heiser@darmarit.de> escreveu: > > > Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>: > > > > > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: > > >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>: > > >> * the pdf goes to the "latex" folder .. since this is WIP > > >> and there are different solutions conceivable ... I left > > >> it open for the first. > > > > > > Mea culpa. As I said, I intended my patches as RFC only. > > > > I think this is OK for the first. I thought that we first > > let finish Mauro's task on making the media PDF and after > > this we decide how move from the latex folder to a pdf folder > > (one solution see below). > > Finished handling all tables. I'm sending the last 2 patches > right now. Now, all tables fit into the page margins. Yet, I > suspect that flat-table extension causes some troubles when cspan > is used for LaTeX. It would be good if Markus could double check them. > > There are just two things that won't fit at the margins of the document: > > 1) included files with long lines. We might put those includes into > a begingroup and use a smaller font, but IMHO the best is to fix the > few cases on them, as those lines are very likely violating the 80 column > limit; > > 2) kernel-doc output for big arguments. > > We have lots of function argument inside several media structs, like > at: > struct v4l2_subdev_core_ops. > > one of such arguments is this function: > > int (* s_io_pin_config) (struct v4l2_subdev *sd, size_t n,struct v4l2_subdev_io_pin_config *pincfg); > > When kernel-doc generates the Members description, as the above line is > bigger than 80 columns, it simply truncates its description to: > > Members > int (*)(struct v4l2_subdev *sd) log_status callback for VIDIOC_LOG_STATUS ioctl handler code. > int (*)(struct v4l2_subdev *sd,size_t n,struct v4l2_subdev_io_pin_config *pincfg) s_io_pin_con > ... > > The LaTeX output for it is: > > \textbf{Members} > \begin{description} > \item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd) log\_status}}] \leavevmode > callback for \sphinxcode{VIDIOC\_LOG\_STATUS} ioctl handler code. > > \item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd, size\_t n,struct v4l2\_subdev\_io\_pin\_config *pincfg) s\_io\_pin\_config}}] \leavevmode > configure one or more chip I/O pins for chips that > multiplex different internal signal pads out to IO pins. This function > takes a pointer to an array of `n' pin configuration entries, one for > each pin being configured. This function could be called at times > other than just subdevice initialization. > > It seems that \sphinxcode{} doesn't allow line breaks. Maybe we can > override it via conf.py. I'll play with it and see if I can find a > solution. Yet, this could have side effects on other places. > > Any suggestions about how to fix it? The problem is actually because Sphinx uses item[], with doesn't split into multiple lines. Doing something like: \\DeclareRobustCommand{\\sphinxcode}[1]{\\begin{minipage}{\\columnwidth}\\texttt{#1}\\end{minipage}} Could fix, but, after sleeping into it, I think that the problem is actually at the way the kernel-doc is output. Right now, for a struct, it produces the following output: .. c:type:: struct v4l2_prio_state stores the priority states **Definition** :: struct v4l2_prio_state { atomic_t prios[4]; }; **Members** ``atomic_t prios[4]`` array with elements to store the array priorities Putting everything inside `` is the culprit for having a very big line there. Also, IMHO, the best would be to output it on a different way, like: **Members** ``prios[4]`` type: ``atomic_t`` array with elements to store the array priorities In order to highlight what really matters: the member name. The type is a secondary information. Also, it is "hidden" in the middle of a long string in the case of function parameters. The order for function parameters is also counter-intuitive, as struct member like: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num); Is currently shown as: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read With sounds weird, at least to my eyes. Also, if the line is too big, on PDF output, the member name will be missed, with is very bad. So, I think that the best solution here is to actually patch kernel-doc, for it to produce the output on a different way: **Members** ``prios[4]`` - **type**: ``atomic_t`` array with elements to store the array priorities With such change, the name of the member will be the first visible thing, and will be in **bold** style. The type will still be there. Also, as the type is not part of LaTeX "item[]", LaTeX will split it into multiple lines, if needed. So, both LaTeX/PDF and HTML outputs will look good. It should be noticed, however, that the way Sphinx LaTeX output handles things like: Foo bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar By starting the second line with a dash, both HTML and LaTeX output will do the same thing. I'm sending the patch for kernel-doc script in a few. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 64460a8..a91c965 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -22,9 +22,15 @@ ifeq ($(DOCBOOKS),) # Skip DocBook build if the user explicitly requested no DOCBOOKS. .DEFAULT: @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." +else +ifneq ($(SPHINXDIRS),) +# Skip DocBook build if the user explicitly requested a sphinx dir +.DEFAULT: + @echo " SKIP DocBook $@ target (SPHINXDIRS specified)." else + ### # The build process is as follows (targets): # (xmldocs) [by docproc] @@ -221,6 +227,7 @@ silent_gen_xml = : echo "</programlisting>") > $@ endif # DOCBOOKS="" +endif # SPHINDIR=... ### # Help targets as used by the top-level makefile diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index fc29e08..ea0664c 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -5,6 +5,9 @@ # You can set these variables from the command line. SPHINXBUILD = sphinx-build SPHINXOPTS = +SPHINXDIRS = . +_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py)) +SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output @@ -33,30 +36,50 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter KERNELDOC = $(srctree)/scripts/kernel-doc KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) -ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src) +ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -quiet_cmd_sphinx = SPHINX $@ - cmd_sphinx = $(MAKE) BUILDDIR=$(BUILDDIR) $(build)=Documentation/media all; BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 +# commands; the 'cmd' from scripts/Kbuild.include is not *loopable* +loop_cmd = $(echo-cmd) $(cmd_$(1)) + +# $2 sphinx builder e.g. "html" +# $3 name of the build subfolder / e.g. "media", used as: +# * dest folder relative to $(BUILDDIR) and +# * cache folder relative to $(BUILDDIR)/.doctrees +# $4 dest subfolder e.g. "man" for man pages at media/man +# $5 reST source folder relative to $(srctree)/$(src), +# e.g. "media" for the linux-tv book-set at ./Documentation/media + +quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4); + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\ + BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ + $(SPHINXBUILD) \ + -b $2 \ + -c $(abspath $(srctree)/$(src)) \ + -d $(abspath $(BUILDDIR)/.doctrees/$3) \ + -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ + $(ALLSPHINXOPTS) \ + $(abspath $(srctree)/$(src)/$5) \ + $(abspath $(BUILDDIR)/$3/$4); htmldocs: - $(call cmd,sphinx,html) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) pdfdocs: ifeq ($(HAVE_PDFLATEX),0) $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX - $(call cmd,sphinx,latex) + @$(call loop_cmd,sphinx,latex,.,latex,.)) $(Q)$(MAKE) -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX epubdocs: - $(call cmd,sphinx,epub) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: - $(call cmd,sphinx,xml) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) # no-ops for the Sphinx toolchain sgmldocs: @@ -76,3 +99,9 @@ dochelp: @echo ' epubdocs - EPUB' @echo ' xmldocs - XML' @echo ' cleandocs - clean all generated files' + @echo + @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' + @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' + @echo + @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' + @echo ' configuration. This is e.g. useful to build with nit-picking config.' diff --git a/Documentation/conf.py b/Documentation/conf.py index b198147..5c06b01 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -19,6 +19,7 @@ import os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('sphinx')) +from load_config import loadConfig # -- General configuration ------------------------------------------------ @@ -421,3 +422,9 @@ pdf_documents = [ # line arguments. kerneldoc_bin = '../scripts/kernel-doc' kerneldoc_srctree = '..' + +# ------------------------------------------------------------------------------ +# Since loadConfig overwrites settings from the global namespace, it has to be +# the last statement in the conf.py file +# ------------------------------------------------------------------------------ +loadConfig(globals()) diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py new file mode 100644 index 0000000..88e5e4a --- /dev/null +++ b/Documentation/sphinx/load_config.py @@ -0,0 +1,33 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +import os +import sys +from sphinx.util.pycompat import execfile_ + +# ------------------------------------------------------------------------------ +def loadConfig(namespace): +# ------------------------------------------------------------------------------ + + u"""Load an additional configuration file into *namespace*. + + The name of the configuration file is taken from the environment + ``SPHINX_CONF``. The external configuration file extends (or overwrites) the + configuration values from the origin ``conf.py``. With this you are able to + maintain *build themes*. """ + + config_file = os.environ.get("SPHINX_CONF", None) + if (config_file is not None + and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): + config_file = os.path.abspath(config_file) + + if os.path.isfile(config_file): + sys.stdout.write("load additional sphinx-config: %s\n" % config_file) + config = namespace.copy() + config['__file__'] = config_file + execfile_(config_file, config) + del config['__file__'] + namespace.update(config) + else: + sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file) +