Commit 77a22121 authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

Merge branch 'tools-final2' into docs-mw 

Our documentation-related tools are spread out over various directories;
several are buried in the scripts/ dumping ground.  That makes them harder
to discover and harder to maintain.

Recent work has started accumulating our documentation-related tools in
/tools/docs.  This series nearly completes that task, moving most of the
rest of our various utilities there, hopefully fixing up all of the
relevant references in the process.

The one exception is scripts/kernel-doc; that move turned up some other
problems, so I have dropped it until those are ironed out.

At the end, rather than move the old, Perl kernel-doc, I simply removed it.
parents e849217c 683e8cba

Documentation/Kconfig

+1 −1
Original line number Diff line number Diff line
@@ -19,7 +19,7 @@ config WARN_ABI_ERRORS 
	  described at Documentation/ABI/README. Yet, as they're manually

	  written, it would be possible that some of those files would

	  have errors that would break them for being parsed by

	  scripts/get_abi.pl. Add a check to verify them.

	  tools/docs/get_abi.py. Add a check to verify them.



	  If unsure, select 'N'.

Documentation/Makefile

+3 −3
Original line number Diff line number Diff line
@@ -8,12 +8,12 @@ subdir- := devicetree/bindings 
ifneq ($(MAKECMDGOALS),cleandocs)

# Check for broken documentation file references

ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)

$(shell $(srctree)/scripts/documentation-file-ref-check --warn)

$(shell $(srctree)/tools/docs/documentation-file-ref-check --warn)

endif



# Check for broken ABI files

ifeq ($(CONFIG_WARN_ABI_ERRORS),y)

$(shell $(srctree)/scripts/get_abi.py --dir $(srctree)/Documentation/ABI validate)

$(shell $(srctree)/tools/docs/get_abi.py --dir $(srctree)/Documentation/ABI validate)

endif

endif
@@ -78,7 +78,7 @@ htmldocs-redirects: $(srctree)/Documentation/.renames.txt 
	@tools/docs/gen-redirects.py --output $(BUILDDIR) < $<



refcheckdocs:

	$(Q)cd $(srctree);scripts/documentation-file-ref-check

	$(Q)cd $(srctree); tools/docs/documentation-file-ref-check



cleandocs:

	$(Q)rm -rf $(BUILDDIR)

Documentation/doc-guide/checktransupdate.rst

+3 −3
Original line number Diff line number Diff line
@@ -27,15 +27,15 @@ Usage 


::



   ./scripts/checktransupdate.py --help

   tools/docs/checktransupdate.py --help



Please refer to the output of argument parser for usage details.



Samples



-  ``./scripts/checktransupdate.py -l zh_CN``

-  ``tools/docs/checktransupdate.py -l zh_CN``

   This will print all the files that need to be updated in the zh_CN locale.

-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``

-  ``tools/docs/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``

   This will only print the status of the specified file.



Then the output is something like:

Documentation/doc-guide/contributing.rst

+1 −1
Original line number Diff line number Diff line
@@ -152,7 +152,7 @@ generate links to that documentation. Adding ``kernel-doc`` directives to 
the documentation to bring those comments in can help the community derive

the full value of the work that has gone into creating them.



The ``scripts/find-unused-docs.sh`` tool can be used to find these

The ``tools/docs/find-unused-docs.sh`` tool can be used to find these

overlooked comments.



Note that the most value comes from pulling in the documentation for

Documentation/doc-guide/sphinx.rst

+1 −1
Original line number Diff line number Diff line
@@ -149,7 +149,7 @@ a venv with it with, and install minimal requirements with:: 


A more comprehensive test can be done by using:



	scripts/test_doc_build.py

	tools/docs/test_doc_build.py



Such script create one Python venv per supported version,

optionally building documentation for a range of Sphinx versions.