Commit 1404f292 authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

Merge branch 'fp' into docs-mw 

The top-level index.rst file is the entry point for the kernel's
documentation, especially for readers of the HTML output.  It is currently
a mess containing everything we thought to throw in there.  Firefox says it
would require 26 pages of paper to print it.  That is not a user-friendly
introduction.

This series aims to improve our documentation entry point with a focus on
rewriting index.rst.  The result is, IMO, simpler and more approachable.
For anybody who wants to see the rendered results without building the
docs, have a look at:

  https://static.lwn.net/kerneldoc/

This time around I've rendered the pages using the "Read The Docs" theme,
since that's what everybody will get by default.  That theme ignores the
directives regarding the left column, so the results are not as good there.
I have a series proposing a default-theme change in the works, but that's a
separate topic.

This is only a beginning; I think this kind of organizational effort has to
be pushed down into the lower layers of the docs tree itself.  But one has
to start somewhere.
parents 49beeea7 48987606

Documentation/conf.py

+2 −1
Original line number Diff line number Diff line
@@ -369,7 +369,8 @@ html_static_path = ['sphinx-static'] 
html_use_smartypants = False



# Custom sidebar templates, maps document names to template names.

#html_sidebars = {}

# Note that the RTD theme ignores this.

html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}



# Additional templates that should be rendered to pages, maps page names to

# template names.

Documentation/asm-annotations.rst→Documentation/core-api/asm-annotations.rst

+4 −3
Original line number Diff line number Diff line
@@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful 
information. In particular, on properly annotated objects, ``objtool`` can be

run to check and fix the object if needed. Currently, ``objtool`` can report

missing frame pointer setup/destruction in functions. It can also

automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>`

automatically generate annotations for the ORC unwinder

(Documentation/x86/orc-unwinder.rst)

for most code. Both of these are especially important to support reliable

stack traces which are in turn necessary for :doc:`Kernel live patching

<livepatch/livepatch>`.

stack traces which are in turn necessary for kernel live patching

(Documentation/livepatch/livepatch.rst).



Caveat and Discussion

---------------------

Documentation/core-api/index.rst

+4 −0
Original line number Diff line number Diff line
@@ -23,6 +23,7 @@ it. 
   printk-formats

   printk-index

   symbol-namespaces

   asm-annotations



Data structures and low-level utilities

=======================================
@@ -44,6 +45,8 @@ Library functionality that is used throughout the kernel. 
   this_cpu_ops

   timekeeping

   errseq

   wrappers/atomic_t

   wrappers/atomic_bitops



Low level entry and exit

========================
@@ -67,6 +70,7 @@ Documentation/locking/index.rst for more related documentation. 
   local_ops

   padata

   ../RCU/index

   wrappers/memory-barriers.rst



Low-level hardware management

=============================

Documentation/core-api/wrappers/atomic_bitops.rst

0 → 100644
+18 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0

   This is a simple wrapper to bring atomic_bitops.txt into the RST world

   until such a time as that file can be converted directly.



=============

Atomic bitops

=============



.. raw:: latex



    \footnotesize



.. include:: ../../atomic_bitops.txt

   :literal:



.. raw:: latex



    \normalsize

Documentation/core-api/wrappers/atomic_t.rst

0 → 100644
+19 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0

   This is a simple wrapper to bring atomic_t.txt into the RST world

   until such a time as that file can be converted directly.



============

Atomic types

============



.. raw:: latex



    \footnotesize



.. include:: ../../atomic_t.txt

   :literal:



.. raw:: latex



    \normalsize