Re: [PATCH 0/3] Add a way to build only media docs

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 07.08.2016 um 14:38 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:

> Em Sun, 7 Aug 2016 11:55:27 +0200
> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
> 
>> 
>> Am 06.08.2016 um 14:00 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
>> 
>>> Being able to build just the media docs is important for us due to several
>>> reasons:
>>> 
>>> 1) Media developers community hosts a copy of the media documentation at linuxtv.org
>>>   with the very latest  under development documents;
>>> 
>>> 2) Nitpicking to identify broken references is important to identify documentation gaps
>>>   that need to be addressed on future releases;
>>> 
>>> 3) As media maintainers check patch per patch if a documentation gap is introduced,
>> 
>> 
>> Take into account: the gap is detected by "open references" (from the reST-header
>> files), but Sphinx tries to bind a ":ref:" to any anchor which fits (no matter where
>> it comes from). I mean, if we add more and more content or e.g. interpshinx objects,
>> we did not know which targets are available and the risk to get a *false bind* grows
>> with the content.
>> 
>> I don't know, may be in some future you will come into trouble, when you want
>> to refer targets outside of the ./media folder and *detect gaps* in the docs.
>> 
>> This need not be a problem, but you should be aware of, that your "test" is
>> only a test on open/closed links.
> 
> Yeah, we'll still have some references outside the media system. There
> are already a few of them at the kABI books, and to get mistakes there,
> we'll need to use nitpick mode for the entire stuff, with can be a
> nightmare, specially since right now we have 300+ missing references just
> inside the media books. We need to address those first, before being able
> to address the external ones.
> 
>>> building
>>>   media documentation should be as fast as possible.
>>> 
>>> This patchset adds a media file adding nitpick support and an extra build target that will
>>> compile only the media documentation. It also groups all media documentation into one
>>> section on the main Kernel document, with is, IMHO, a good thing as we start adding more
>>> stuff there.
>>> 
>>> Jon,
>>> 
>>> I'd love to see this patch merged early at the -rc cycle, in order to avoid merge
>>> conflicts when people start converting other docbooks to Sphinx, as it touches
>>> at the main Makefile and at the Sphinx common stuff. Also, as I'll need to patch my
>>> build scripts to check for documentation issues with Sphinx, I need them on my
>>> master branch, as otherwise my workflow will be broken until the next Kernel release.
>>> 
>>> So, If you're ok with this patch series, can you submit to Linus on early -rc? Or 
>>> if you prefer, I can do it myself, with your ack.
>>> 
>>> Thanks!
>>> Mauro
>>> 
>>> PS.: I would prefer to have a more generic way to add support to build documentation
>>> for only one subsystem, but, as we also need to load an extra python module to be
>>> able to enable nitpick mode, I opted, for now, on not doing it too generic. We can rework
>>> on it later, as other subsystems would need a similar feature.
>> 
>> Within my POC I called it "books", may it is better to call them "sphinx-projects",
>> but for the first and the concept it should good enough to stay with "books" / see 
>> Makefile.reST [1] ::
>> 
>> # Sphinx projects, we call them *books* which is more common to authors.
> 
> The nomenclature can be very confusing, specially when we're grouping
> different documents altogether.
> 
> The way I see, at the media subsystem, there are 4 books:
> 	- uAPI - with has internally 5 parts;
> 	- kAPI;
> 	- V4L drivers;
> 	- DVB drivers.
> 
> Yet, IMHO, the best is to put one master index.rst pointing to all of
> them, so we actually have a media "book set", and just one "override"
> conf.py for all of them. So, for now, I guess it is OK to group them 
> altogether when checking for references, although in reality, at least 
> in the first moment, I'm only interested on fixing bad references at
> the uAPI and kAPI books. The other two books have lots of legacy stuff
> that needs to be updated before even looking into any bad references there.
> 
> Yet, at the makefile, I don't mind calling the book set as "BOOK".
> 
> 
>> BOOKS_FOLDER = $(obj)/Documentation
>> BOOKS=$(filter-out books/intro, \
>>    $(patsubst $(BOOKS_FOLDER)/%/conf.py,books/%,$(wildcard $(BOOKS_FOLDER)/*/conf.py)) \
>>    )
>> 
>> # fine grained targets
>> BOOKS_HTML = $(patsubst %,%.html, $(BOOKS))
>> BOOKS_CLEAN = $(patsubst %,%.clean, $(BOOKS))
>> BOOKS_MAN = $(patsubst %,%.man, $(BOOKS))
>> BOOKS_PDF = $(patsubst %,%.pdf, $(BOOKS))
>> 
>> [1] https://github.com/return42/sphkerneldoc/blob/master/doc/Makefile#L40
>> 
>> In words: A "book" (or sphinx-project) is a folder with a conf.py in
>> and the "folder-name" is the name of the related target ::
>> 
>>  Documentation/*/conf.py
>> 
>> And the selective targets are
>> 
>>  make books/[media|...].[html|man|pdf|clean|...]
>> 
>> By example, build only the html of media::
>> 
>>  make books/media.html
>> 
>> The integration into the main Makefile is generic by adding the
>> wildcard target "books%"
>> 
>> modified   Makefile
>> @@ -478,7 +478,7 @@ version_h := include/generated/uapi/linux/version.h
>> old_version_h := include/linux/version.h
>> 
>> no-dot-config-targets := clean mrproper distclean \
>> -			 cscope gtags TAGS tags help% %docs check% coccicheck \
>> +			 cscope gtags TAGS tags help% %docs books% check% coccicheck \
>> 			 $(version_h) headers_% archheaders archscripts \
>> 			 kernelversion %src-pkg
>> 
>> +# more fine grained documentation targets
>> +books/%:
>> +	$(Q)$(MAKE) $(build)=Documentation -f Documentation/Makefile.reST $@
>> +
>> 
>> 
>> If you are interested in, I prepare a patch series for the Makefiles and the
>> conf.py.
> 
> Interesting approach. That would work for me. Not sure what the others
> think about that.
> 
> Yet, my understanding is that we should have just one conf.py
> for the "all-in-one" book (e. g. Documentation/index.rst), plus 
> additional ones to be used where we want to build standalone books 
> with nitpick mode enabled.
> 
> So, we should keep having the
> 	make htmldocs
> 
> target that would build the all-in-one book, plus some other way to
> build those books that would have a conf.py that would be adding the
> extra nitpick options.
> 
> I really don't mind if we'll be compiling those with:
> 	make books/media.html
> 
> or with something like:
> 	make SPHINXDIRS="./media" htmldocs
> 
> Actually, the last syntax is better, IMHO, because people are already
> familiar with something similar to that.
> 
> Provided that it would work and the patch would be simple enough to
> be added on an early -rc Kernel (or alternatively, if it can be
> sent via my master devel branch with Jon's ack).

Hi Mauro,

I agree with all, nevertheless I think, building a partial product should
be a make target. Anyway, I prepare a patch (with SPHINXDIRS="./media") 
on top of your patch series.

-- Markus --




--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Linux Input]     [Video for Linux]     [Gstreamer Embedded]     [Mplayer Users]     [Linux USB Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [Yosemite Backpacking]
  Powered by Linux