diff mbox

[Ksummit-discuss] Including images on Sphinx documents

Message ID a6b88e7d-9d6b-4dcc-3d2e-c09bdf366b40@darmarit.de (mailing list archive)
State New, archived
Headers show

Commit Message

Markus Heiser Nov. 9, 2016, 10:11 p.m. UTC 
On 09.11.2016 12:58, Jani Nikula wrote:
 > On Wed, 09 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
 >> Am 09.11.2016 um 12:16 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
 >>>> So I vote for :
 >>>>
 >>>>> 1) copy (or symlink) all rst files to Documentation/output (or to the
 >>>>> build dir specified via O= directive) and generate the *.pdf there,
 >>>>> and produce those converted images via Makefile.;
 >>>
 >>> We're supposed to solve problems, not create new ones.
 >>
 >> ... new ones? ...
 >
 > Handle in-tree builds without copying.
 >
 > Make dependency analysis with source rst and "intermediate" rst work.
 >
 > Make sure your copying gets the timestamps right.
 >
 > Make Sphinx dependency analysis look at the right copies depending on
 > in-tree vs. out-of-tree. Generally make sure it doesn't confuse Sphinx's
 > own dependency analysis.
 >
 > The stuff I didn't think of.

It might be easier than you think first.

 > Sure, it's all supposed to be basic Makefile stuff, but don't make the mistake
 > of thinking just one invocation of 'cp' will solve all the problems.

I act naif using 'cp -sa', see patch below.

 > It all adds to the complexity we were trying to avoid when dumping DocBook. It
 > adds to the complexity of debugging stuff. (And hey, there's still the one
 > rebuilding-stuff-for-no-reason issue open.)

And hey ;-) I wrote you [1], this is a bug in Sphinx. Yes, I haven't had time
to send a bugfix to Sphinx, but this won't even help us (bugfixes in Sphinx will
only apply on top).

 > If you want to keep the documentation build sane, try to avoid the Makefile
 > preprocessing.

I'am just the one helping Mauro to be productive, if he needs preprocessing I
implement proposals. I know that you fear preprocessing since it tend to
fall-back, what we had with DocBook's build process.  We discussed this already,
it might better you unify this with Mauro and the other who need preprocessing.

 > And same old story, if you fix this for real, even if as a Sphinx extension,
 > *other* people than kernel developers will be interested, and *we* don't have
 > to do so much ourselves.

I don't think so, this kind of parsing header files we have and the build of
content from MAINTAINERS, ABI, etc. is very kernel specific.

Anyway, back to my point 'copy (or symlink) all rst files'. Please take a look
at my patch below. Take in mind; its just a POC.

Could this POC persuade you, if so, I send a more elaborate RFC,
what do you think about?

[1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg07302.html

-- Markus --

 > BR,
 > Jani.
 >>
 >>>> IMO placing 'sourcedir' to O= is more sane since this marries the
 >>>> Linux Makefile concept (relative to $PWD) with the sphinx concept
 >>>> (in or below 'sourcedir').
 >>
 >> -- Markus --
 >

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

Comments

Jani Nikula Nov. 10, 2016, 10:35 a.m. UTC | #1 
On Thu, 10 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Could this POC persuade you, if so, I send a more elaborate RFC,
> what do you think about?

Sorry, I do not wish to be part of this.

BR,
Jani.
Jani Nikula Nov. 11, 2016, 11:22 a.m. UTC | #2 
On Thu, 10 Nov 2016, Jani Nikula <jani.nikula@linux.intel.com> wrote:
> On Thu, 10 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>> Could this POC persuade you, if so, I send a more elaborate RFC,
>> what do you think about?
>
> Sorry, I do not wish to be part of this.

That was uncalled for, apologies.

Like I said, I don't think this is the right approach. Call it an
unsubstantiated gut feel coming from experience. However, I do not have
the time to properly dig into this either, and that frustrates me. I
wish I could be more helpful, but I can't right now.

BR,
Jani.
Markus Heiser Nov. 11, 2016, 11:45 a.m. UTC | #3 
Am 11.11.2016 um 12:22 schrieb Jani Nikula <jani.nikula@linux.intel.com>:

> On Thu, 10 Nov 2016, Jani Nikula <jani.nikula@linux.intel.com> wrote:
>> On Thu, 10 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>>> Could this POC persuade you, if so, I send a more elaborate RFC,
>>> what do you think about?
>> 
>> Sorry, I do not wish to be part of this.
> 
> That was uncalled for, apologies.

It's OK, sometimes we are all in a hurry and want shorten things.

> Like I said, I don't think this is the right approach. Call it an
> unsubstantiated gut feel coming from experience.

Yes, building a bunch of symbolic links "smells". Unfortunately,
I currently see no other solution to solve the conflict of 
Linux's "O=/foo" and Sphinx's "sourcedir", so that was my
proposal.

> However, I do not have
> the time to properly dig into this either, and that frustrates me. I
> wish I could be more helpful, but I can't right now.

its a pity

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

Patch

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index ec0c77d..8e904c1 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -13,6 +13,10 @@  BUILDDIR      = $(obj)/output
  PDFLATEX      = xelatex
  LATEXOPTS     = -interaction=batchmode

+ifdef SPHINXDIRS
+else
+endif
+
  # User-friendly check for sphinx-build
  HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)

@@ -50,30 +54,38 @@  loop_cmd = $(echo-cmd) $(cmd_$(1))
  #    * 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),
+# $5 reST source folder relative to $(obj),
  #    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)) \
+      cmd_sphinx = $(MAKE) BUILDDIR=$(BUILDDIR) $(build)=Documentation/media all;\
+	BUILDDIR=$(BUILDDIR) SPHINX_CONF=$(obj)/$5/$(SPHINX_CONF) \
  	$(SPHINXBUILD) \
  	-b $2 \
-	-c $(abspath $(srctree)/$(src)) \
-	-d $(abspath $(BUILDDIR)/.doctrees/$3) \
+	-c $(obj) \
+	-d $(obj)/.doctrees/$3 \
  	-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
  	$(ALLSPHINXOPTS) \
-	$(abspath $(srctree)/$(src)/$5) \
-	$(abspath $(BUILDDIR)/$3/$4);
-
-htmldocs:
+	$(obj)/$5 \
+	$(BUILDDIR)/$3/$4;
+
+ifdef O
+sync:
+	rm -rf $(objtree)/$(obj)
+	cp -sa $(srctree)/$(obj) $(objtree)
+else
+sync:
+endif
+
+htmldocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

-latexdocs:
+latexdocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))

  ifeq ($(HAVE_PDFLATEX),0)

-pdfdocs:
+pdfdocs: sync
  	$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
  	@echo "  SKIP    Sphinx $@ target."

@@ -84,10 +96,10 @@  pdfdocs: latexdocs

  endif # HAVE_PDFLATEX

-epubdocs:
+epubdocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))

-xmldocs:
+xmldocs: sync
  	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))

  # no-ops for the Sphinx toolchain
@@ -98,6 +110,7 @@  installmandocs:

  cleandocs:
  	$(Q)rm -rf $(BUILDDIR)
+	$(Q)rm -rf $(obj)/.doctrees

  endif # HAVE_SPHINX