* [PATCH 1/5] doc: replace nocast-vs-bitwise document with its lore link
2020-08-09 14:17 [PATCH 0/5] improve presenttation of the documentation Luc Van Oostenryck
@ 2020-08-09 14:17 ` Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 2/5] doc: simplify the toctree Luc Van Oostenryck
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Luc Van Oostenryck @ 2020-08-09 14:17 UTC (permalink / raw)
To: linux-sparse; +Cc: 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
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH 2/5] doc: simplify the toctree
2020-08-09 14:17 [PATCH 0/5] improve presenttation of the documentation Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 1/5] doc: replace nocast-vs-bitwise document with its lore link Luc Van Oostenryck
@ 2020-08-09 14:17 ` Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 3/5] doc: add index to the sidebar Luc Van Oostenryck
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Luc Van Oostenryck @ 2020-08-09 14:17 UTC (permalink / raw)
To: linux-sparse; +Cc: 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
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH 3/5] doc: add index to the sidebar
2020-08-09 14:17 [PATCH 0/5] improve presenttation of the documentation Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 1/5] doc: replace nocast-vs-bitwise document with its lore link Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 2/5] doc: simplify the toctree Luc Van Oostenryck
@ 2020-08-09 14:17 ` Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 4/5] doc: remove link "edit on github" Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 5/5] doc: shorter title for "submitting-patches.md" Luc Van Oostenryck
4 siblings, 0 replies; 6+ messages in thread
From: Luc Van Oostenryck @ 2020-08-09 14:17 UTC (permalink / raw)
To: linux-sparse; +Cc: 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
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH 4/5] doc: remove link "edit on github"
2020-08-09 14:17 [PATCH 0/5] improve presenttation of the documentation Luc Van Oostenryck
` (2 preceding siblings ...)
2020-08-09 14:17 ` [PATCH 3/5] doc: add index to the sidebar Luc Van Oostenryck
@ 2020-08-09 14:17 ` Luc Van Oostenryck
2020-08-09 14:17 ` [PATCH 5/5] doc: shorter title for "submitting-patches.md" Luc Van Oostenryck
4 siblings, 0 replies; 6+ messages in thread
From: Luc Van Oostenryck @ 2020-08-09 14:17 UTC (permalink / raw)
To: linux-sparse; +Cc: 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
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH 5/5] doc: shorter title for "submitting-patches.md"
2020-08-09 14:17 [PATCH 0/5] improve presenttation of the documentation Luc Van Oostenryck
` (3 preceding siblings ...)
2020-08-09 14:17 ` [PATCH 4/5] doc: remove link "edit on github" Luc Van Oostenryck
@ 2020-08-09 14:17 ` Luc Van Oostenryck
4 siblings, 0 replies; 6+ messages in thread
From: Luc Van Oostenryck @ 2020-08-09 14:17 UTC (permalink / raw)
To: linux-sparse; +Cc: 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
^ permalink raw reply related [flat|nested] 6+ messages in thread