[PATCH 0/5] improve presenttation of the documentation

[PATCH 0/5] improve presenttation of the documentation

[Luc Van Oostenryck]

This series contains a few small improvements to the documentation,
mainly to the sidebar of the online documentation.

This series is available for review & testing at:
  git://github.com/lucvoo/sparse-dev.git doc-annot

Luc Van Oostenryck (5):
  doc: replace nocast-vs-bitwise document with its lore link
  doc: simplify the toctree
  doc: add index to the sidebar
  doc: remove link "edit on github"
  doc: shorter title for "submitting-patches.md"

 Documentation/index.rst                  | 29 ++++------------
 Documentation/nocast-vs-bitwise.md       | 43 ------------------------
 Documentation/submitting-patches.md      |  4 +--
 Documentation/templates/breadcrumbs.html | 11 ++++++
 Documentation/templates/layout.html      |  8 +++++
 5 files changed, 28 insertions(+), 67 deletions(-)
 delete mode 100644 Documentation/nocast-vs-bitwise.md
 create mode 100644 Documentation/templates/breadcrumbs.html
 create mode 100644 Documentation/templates/layout.html


base-commit: bdf3eca7298e5d57864c83329e979a7746d7c130
-- 
2.28.0

[PATCH 1/5] doc: replace nocast-vs-bitwise document with its lore link

[Luc Van Oostenryck]

The nocast-vs-bitwise document was copied here to be sure
to remain accessible but isn't really useful here now because:
1) the original document have also been archived to lore.kernel.org
2) nocast & bitwise have now been documented
3) 2) contains a link to 1)

So, remove this redundant document.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/index.rst            |  1 -
 Documentation/nocast-vs-bitwise.md | 43 ------------------------------
 2 files changed, 44 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9c76419ba5dd..cbe0521b7091 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -69,7 +69,6 @@ User documentation
    :maxdepth: 1
 
    annotations
-   nocast-vs-bitwise
 
 Developer documentation
 -----------------------
diff --git a/Documentation/nocast-vs-bitwise.md b/Documentation/nocast-vs-bitwise.md
deleted file mode 100644
index 9ba5a789fc26..000000000000
--- a/Documentation/nocast-vs-bitwise.md
+++ /dev/null
@@ -1,43 +0,0 @@
-__nocast vs __bitwise
-=====================
-
-`__nocast` warns about explicit or implicit casting to different types.
-HOWEVER, it doesn't consider two 32-bit integers to be different
-types, so a `__nocast int` type may be returned as a regular `int`
-type and then the `__nocast` is lost.
-
-So `__nocast` on integer types is usually not that powerful. It just
-gets lost too easily. It's more useful for things like pointers. It
-also doesn't warn about the mixing: you can add integers to `__nocast`
-integer types, and it's not really considered anything wrong.
-
-`__bitwise` ends up being a *stronger integer separation*. That one
-doesn't allow you to mix with non-bitwise integers, so now it's much
-harder to lose the type by mistake.
-
-So the basic rule is:
-
-- `__nocast` on its own tends to be more useful for *big* integers
-  that still need to act like integers, but you want to make it much
-  less likely that they get truncated by mistake. So a 64-bit integer
-  that you don't want to mistakenly/silently be returned as `int`, for
-  example. But they mix well with random integer types, so you can add
-  to them etc without using anything special. However, that mixing also
-  means that the `__nocast` really gets lost fairly easily.
-
-- `__bitwise` is for *unique types* that cannot be mixed with other
-  types, and that you'd never want to just use as a random integer (the
-  integer `0` is special, though, and gets silently accepted - it's
-  kind of like `NULL` for pointers). So `gfp_t` or the `safe endianness`
-  types would be `__bitwise`: you can only operate on them by doing
-  specific operations that know about *that* particular type.
-
-Generally, you want `__bitwise` if you are looking for type safety.
-`__nocast` really is pretty weak.
-
-Reference:
-----------
-
-* Linus' e-mail about `__nocast` vs `__bitwise`:
-
-  <https://marc.info/?l=linux-mm&m=133245421127324&w=2>
-- 
2.28.0

[PATCH 2/5] doc: simplify the toctree

[Luc Van Oostenryck]

Combine the 'user' documentation with the one for developers
and add captions for each sections in order to have this
structuration visible in the sidebar.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/index.rst | 28 +++++++---------------------
 1 file changed, 7 insertions(+), 21 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index cbe0521b7091..e8e40c0cd109 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -63,42 +63,28 @@ To subscribe to the list, send an email with
 Bugs can also be reported and tracked via the Linux kernel's bugzilla:
 http://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools.
 
-User documentation
-------------------
-.. toctree::
-   :maxdepth: 1
-
-   annotations
 
-Developer documentation
------------------------
 .. toctree::
+   :caption: Documentation
    :maxdepth: 1
 
-   test-suite
+   annotations
    dev-options
+   types
    api
    IR
-   types
+   test-suite
+   doc-guide
 
-How to contribute
------------------
 .. toctree::
+   :caption: How to contribute
    :maxdepth: 1
 
    submitting-patches
    TODO
 
-Documentation
--------------
-.. toctree::
-   :maxdepth: 1
-
-   doc-guide
-
-Release Notes
--------------
 .. toctree::
+   :caption: Release Notes
    :maxdepth: 1
 
    release-notes/index
-- 
2.28.0

[PATCH 3/5] doc: add index to the sidebar

[Luc Van Oostenryck]

It's very useful to be able to access the index from the sidebar
but no change in the configuration seems to allow this. Trying
to abuse the toctree give the same result.

So, add it directly via the template system.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/templates/layout.html | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/templates/layout.html b/Documentation/templates/layout.html
new file mode 100644
index 000000000000..a2fe215fcef6
--- /dev/null
+++ b/Documentation/templates/layout.html
@@ -0,0 +1,8 @@
+{% extends "!layout.html" %}
+{% block menu %}
+    {{ super() }}
+    <p class="caption"><span class="caption-text">Index</span></p>
+    <ul>
+    <li class="toctree-l1"><a class="reference internal" href="{{ pathto('genindex') }}">Index</a></li>
+    </ul>
+{% endblock %}
-- 
2.28.0

[PATCH 4/5] doc: remove link "edit on github"

[Luc Van Oostenryck]

since the development isn't done on github, the link "edit on github"
is useless and confusing.

So remove this link (but leave the one "View page source" as it's
sometimes quite handy).

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/templates/breadcrumbs.html | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/templates/breadcrumbs.html b/Documentation/templates/breadcrumbs.html
new file mode 100644
index 000000000000..4f22fa9a8163
--- /dev/null
+++ b/Documentation/templates/breadcrumbs.html
@@ -0,0 +1,11 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+  {% if hasdoc(pagename) %}
+    <li class="wy-breadcrumbs-aside">
+    {% if show_source and has_source and sourcename %}
+      <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+    {% endif %}
+    </li>
+  {% endif %}
+{% endblock %}
-- 
2.28.0

[PATCH 5/5] doc: shorter title for "submitting-patches.md"

[Luc Van Oostenryck]

The documentation for submitting patches has ": the sparse version"
is in its title. This is quite useless and makes it longer than
needed.

So, remove this part from the title.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/submitting-patches.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/submitting-patches.md b/Documentation/submitting-patches.md
index fb176ce51d46..6a4275c3fd35 100644
--- a/Documentation/submitting-patches.md
+++ b/Documentation/submitting-patches.md
@@ -1,5 +1,5 @@
-Submitting patches: the sparse version
-======================================
+Submitting patches
+==================
 
 Sparse uses a patch submit process similar to the Linux Kernel
 [Submitting Patches](https://www.kernel.org/doc/html/v4.12/process/submitting-patches.html)
-- 
2.28.0