Commit 0f776dc3 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'docs-for-linus' of git://git.lwn.net/linux 

Pull documentation updates from Jonathan Corbet:
 "Some big changes this month, headlined by the addition of a new
  formatted documentation mechanism based on the Sphinx system.

  The objectives here are to make it easier to create better-integrated
  (and more attractive) documents while (eventually) dumping our
  one-of-a-kind, cobbled-together system for something that is widely
  used and maintained by others.  There's a fair amount of information
  what's being done, why, and how to use it in:

    https://lwn.net/Articles/692704/
    https://lwn.net/Articles/692705/

  Closer to home, Documentation/kernel-documentation.rst describes how
  it works.

  For now, the new system exists alongside the old one; you should soon
  see the GPU documentation converted over in the DRM pull and some
  significant media conversion work as well.  Once all the docs have
  been moved over and we're convinced that the rough edges (of which are
  are a few) have been smoothed over, the DocBook-based stuff should go
  away.

  Primary credit is to Jani Nikula for doing the heavy lifting to make
  this stuff actually work; there has also been notable effort from
  Markus Heiser, Daniel Vetter, and Mauro Carvalho Chehab.

  Expect a couple of conflicts on the new index.rst file over the course
  of the merge window; they are trivially resolvable.  That file may be
  a bit of a conflict magnet in the short term, but I don't expect that
  situation to last for any real length of time.

  Beyond that, of course, we have the usual collection of tweaks,
  updates, and typo fixes"

* tag 'docs-for-linus' of git://git.lwn.net/linux: (77 commits)
  doc-rst: kernel-doc: fix handling of address_space tags
  Revert "doc/sphinx: Enable keep_warnings"
  doc-rst: kernel-doc directive, fix state machine reporter
  docs: deprecate kernel-doc-nano-HOWTO.txt
  doc/sphinx: Enable keep_warnings
  Documentation: add watermark_scale_factor to the list of vm systcl file
  kernel-doc: Fix up warning output
  docs: Get rid of some kernel-documentation warnings
  doc-rst: add an option to ignore DocBooks when generating docs
  workqueue: Fix a typo in workqueue.txt
  Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
  Documentation/sphinx: skip build if user requested specific DOCBOOKS
  Documentation: add cleanmediadocs to the documentation targets
  Add .pyc files to .gitignore
  Doc: PM: Fix a typo in intel_powerclamp.txt
  doc-rst: flat-table directive - initial implementation
  Documentation: add meta-documentation for Sphinx and kernel-doc
  Documentation: tiny typo fix in usb/gadget_multi.txt
  Documentation: fix wrong value in md.txt
  bcache: documentation formatting, edited for clarity, stripe alignment notes
  ...
parents 015cd867 a88b1672

Documentation/.gitignore

0 → 100644
+2 −0
Original line number Diff line number Diff line 
output

*.pyc

Documentation/00-INDEX

+2 −2
Original line number Diff line number Diff line
@@ -255,10 +255,10 @@ kbuild/ 
	- directory with info about the kernel build process.

kdump/

	- directory with mini HowTo on getting the crash dump code to work.

kernel-doc-nano-HOWTO.txt

	- mini HowTo on generation and location of kernel documentation files.

kernel-docs.txt

	- listing of various WWW + books that document kernel internals.

kernel-documentation.rst

	- how to write and format reStructuredText kernel documentation

kernel-parameters.txt

	- summary listing of command line / boot prompt args for the kernel.

kernel-per-CPU-kthreads.txt

Documentation/CodingStyle

+1 −1
Original line number Diff line number Diff line
@@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does 
it.



When commenting the kernel API functions, please use the kernel-doc format.

See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc

See the files Documentation/kernel-documentation.rst and scripts/kernel-doc

for details.



Linux style for comments is the C89 "/* ... */" style.

Documentation/DocBook/Makefile

+24 −6
Original line number Diff line number Diff line
@@ -6,6 +6,8 @@ 
# To add a new book the only step required is to add the book to the

# list of DOCBOOKS.



ifeq ($(IGNORE_DOCBOOKS),)



DOCBOOKS := z8530book.xml device-drivers.xml \

	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \

	    writing_usb_driver.xml networking.xml \
@@ -33,10 +35,6 @@ PDF_METHOD = $(prefer-db2x) 
PS_METHOD	= $(prefer-db2x)





###

# The targets that may be used.

PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs



targets += $(DOCBOOKS)

BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))

xmldocs: $(BOOKS)
@@ -63,6 +61,9 @@ installmandocs: mandocs 
		sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \

		xargs install -m 644 -t /usr/local/man/man9/



# no-op for the DocBook toolchain

epubdocs:



###

#External programs used

KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
@@ -216,10 +217,24 @@ silent_gen_xml = : 
	       -e "s/>/\\>/g";     \

	   echo "</programlisting>")  > $@



else



# Needed, due to cleanmediadocs

include Documentation/DocBook/media/Makefile



htmldocs:

pdfdocs:

psdocs:

xmldocs:

installmandocs:



endif # IGNORE_DOCBOOKS





###

# Help targets as used by the top-level makefile

dochelp:

	@echo  ' Linux kernel internal documentation in different formats:'

	@echo  ' Linux kernel internal documentation in different formats (DocBook):'

	@echo  '  htmldocs        - HTML'

	@echo  '  pdfdocs         - PDF'

	@echo  '  psdocs          - Postscript'
@@ -230,6 +245,9 @@ dochelp: 
	@echo

	@echo  '  make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'

	@echo  '  valid values for DOCBOOKS are: $(DOCBOOKS)'

	@echo

	@echo  "  make IGNORE_DOCBOOKS=1 [target] Don't generate docs from Docbook"

	@echo  '     This is useful to generate only the ReST docs (Sphinx)'





###

Documentation/Makefile.sphinx

0 → 100644
+78 −0
Original line number Diff line number Diff line 
# -*- makefile -*-

# Makefile for Sphinx documentation

#



# You can set these variables from the command line.

SPHINXBUILD   = sphinx-build

SPHINXOPTS    =

PAPER         =

BUILDDIR      = $(obj)/output



# User-friendly check for sphinx-build

HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)



ifeq ($(HAVE_SPHINX),0)



.DEFAULT:

	$(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)

	@echo "  SKIP    Sphinx $@ target."



else ifneq ($(DOCBOOKS),)



# Skip Sphinx build if the user explicitly requested DOCBOOKS.

.DEFAULT:

	@echo "  SKIP    Sphinx $@ target (DOCBOOKS specified)."



else # HAVE_SPHINX



# User-friendly check for rst2pdf

HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)



# Internal variables.

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)

# the i18n builder cannot share the environment and doctrees with the others

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .



quiet_cmd_sphinx = SPHINX  $@

      cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2



htmldocs:

	$(call cmd,sphinx,html)



pdfdocs:

ifeq ($(HAVE_RST2PDF),0)

	$(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)

	@echo "  SKIP    Sphinx $@ target."

else # HAVE_RST2PDF

	$(call cmd,sphinx,pdf)

endif # HAVE_RST2PDF



epubdocs:

	$(call cmd,sphinx,epub)



xmldocs:

	$(call cmd,sphinx,xml)



# no-ops for the Sphinx toolchain

sgmldocs:

psdocs:

mandocs:

installmandocs:

cleanmediadocs:



cleandocs:

	$(Q)rm -rf $(BUILDDIR)



dochelp:

	@echo  ' Linux kernel internal documentation in different formats (Sphinx):'

	@echo  '  htmldocs        - HTML'

	@echo  '  pdfdocs         - PDF'

	@echo  '  epubdocs        - EPUB'

	@echo  '  xmldocs         - XML'

	@echo  '  cleandocs       - clean all generated files'



endif # HAVE_SPHINX

CRA Git | Maintained and supported by SUSTech CRA and CCSE