[PATCH 0/7] doc: small tweaks to the online documentation

[PATCH 0/7] doc: small tweaks to the online documentation

[Luc Van Oostenryck]

This series contains some adjustment to the spacing in the generated
HTML and some small changes in the content of the main page.

Luc Van Oostenryck (7):
  doc: use a smaller logo in the sidebar
  doc: make the sidebar more compact
  doc: decrease vertical spacing
  doc: move down info about tarballs, after git repositories
  doc: reorganize the table of content
  doc: use shorter titles
  doc: add links to some external doc

 Documentation/IR.rst                          |  4 +--
 Documentation/conf.py                         |  8 +++++-
 Documentation/dev-options.rst                 |  4 +--
 Documentation/doc-guide.rst                   |  4 +--
 Documentation/index.rst                       | 26 +++++++++++--------
 .../sphinx/static/theme_overrides.css         | 20 ++++++++++++++
 Documentation/types.rst                       |  6 ++---
 7 files changed, 51 insertions(+), 21 deletions(-)
 create mode 100644 Documentation/sphinx/static/theme_overrides.css


base-commit: 6fe6d05b56815966b452b0363c9ffd11e1787f85
-- 
2.28.0

[PATCH 1/7] doc: use a smaller logo in the sidebar

[Luc Van Oostenryck]

The logo takes quite a bit height in the sidebar and so
pushes the table of content too much at the bottom.

Fix this by reducing the logo to 50%.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/conf.py                           | 8 +++++++-
 Documentation/sphinx/static/theme_overrides.css | 3 +++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 89ba3d785c7a..affa907346c0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -113,7 +113,13 @@ except:
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['sphinx/static']
+html_static_path = ['sphinx/static']
+
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',
+    ],
+}
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
diff --git a/Documentation/sphinx/static/theme_overrides.css b/Documentation/sphinx/static/theme_overrides.css
new file mode 100644
index 000000000000..8d6246e4202c
--- /dev/null
+++ b/Documentation/sphinx/static/theme_overrides.css
@@ -0,0 +1,3 @@
+.wy-side-nav-search > a img.logo {
+	width: 60%;
+}
-- 
2.28.0

[PATCH 2/7] doc: make the sidebar more compact

[Luc Van Oostenryck]

There is generous spacing in the sidebar, too generous.

So, reduce it to something more compact, which will also
allow more entries without scrolling.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/sphinx/static/theme_overrides.css | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/sphinx/static/theme_overrides.css b/Documentation/sphinx/static/theme_overrides.css
index 8d6246e4202c..8791046c9013 100644
--- a/Documentation/sphinx/static/theme_overrides.css
+++ b/Documentation/sphinx/static/theme_overrides.css
@@ -1,3 +1,7 @@
+.wy-menu-vertical a, .wy-menu-vertical li.current > a, .wy-menu-vertical p.caption {
+	padding: 0.2em 1.2em;
+}
+
 .wy-side-nav-search > a img.logo {
 	width: 60%;
 }
-- 
2.28.0

[PATCH 3/7] doc: decrease vertical spacing

[Luc Van Oostenryck]

The vertical spacing in the generated HTML is a bit excessive
to my taste. So decrease it somehow, especially the top of lists.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/sphinx/static/theme_overrides.css | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/sphinx/static/theme_overrides.css b/Documentation/sphinx/static/theme_overrides.css
index 8791046c9013..3e4bc3b0223a 100644
--- a/Documentation/sphinx/static/theme_overrides.css
+++ b/Documentation/sphinx/static/theme_overrides.css
@@ -1,3 +1,16 @@
+p {
+	margin-bottom: 0.6em;
+}
+
+ul.simple {
+	margin-top: -0.5em;
+	margin-bottom: 0.5em;
+}
+
+.rst-content .toctree-wrapper ul {
+	margin-bottom: 0.5em;
+}
+
 .wy-menu-vertical a, .wy-menu-vertical li.current > a, .wy-menu-vertical p.caption {
 	padding: 0.2em 1.2em;
 }
-- 
2.28.0

[PATCH 4/7] doc: move down info about tarballs, after git repositories

[Luc Van Oostenryck]

Better to have the information about the GIT repositories
first because I'm not sure if anyone still use the tarballs.

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

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 4047343a5a75..321a947ec9c5 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -25,9 +25,6 @@ by Christopher Li in 2009 and by Luc Van Oostenryck in late 2018.
 Getting Sparse
 --------------
 
-You can find tarballs of released versions of Sparse at
-https://www.kernel.org/pub/software/devel/sparse/dist/.
-
 The most recent version can be obtained directly from the Git
 repository with the command::
 
@@ -35,6 +32,8 @@ repository with the command::
 
 You can also `browse the Git repository <https://git.kernel.org/pub/scm/devel/sparse/sparse.git>`_
 or use the mirror at https://github.com/lucvoo/sparse.
+The tarballs of released versions of Sparse and their signatures can be found at
+https://www.kernel.org/pub/software/devel/sparse/dist/.
 
 Once you have the sources, to build Sparse and install it in your ~/bin
 directory, just do::
-- 
2.28.0

[PATCH 5/7] doc: reorganize the table of content

[Luc Van Oostenryck]

Reorganize the table of of content with user documentation first
then all documentation useful for development on sparse itself.

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

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 321a947ec9c5..4bca8c7e47f3 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -64,22 +64,22 @@ Bugs can also be reported and tracked via the `Linux kernel's bugzilla for spars
 
 
 .. toctree::
-   :caption: Documentation
+   :caption: User Documentation
    :maxdepth: 1
 
    annotations
-   dev-options
-   types
-   api
-   IR
-   test-suite
-   doc-guide
 
 .. toctree::
-   :caption: How to contribute
+   :caption: Development
    :maxdepth: 1
 
    submitting-patches
+   types
+   api
+   dev-options
+   IR
+   test-suite
+   doc-guide
    TODO
 
 .. toctree::
-- 
2.28.0

[PATCH 6/7] doc: use shorter titles

[Luc Van Oostenryck]

Mainly it's removing 'sparse' from the title.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
---
 Documentation/IR.rst          | 4 ++--
 Documentation/dev-options.rst | 4 ++--
 Documentation/doc-guide.rst   | 4 ++--
 Documentation/types.rst       | 6 +++---
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/IR.rst b/Documentation/IR.rst
index 33a761662fad..97d4b2b27ee3 100644
--- a/Documentation/IR.rst
+++ b/Documentation/IR.rst
@@ -1,7 +1,7 @@
 .. default-domain:: ir
 
-Sparse's Intermediate Representation
-====================================
+Intermediate Representation
+===========================
 
 Instructions
 ~~~~~~~~~~~~
diff --git a/Documentation/dev-options.rst b/Documentation/dev-options.rst
index 23e8096c2cd0..57f9e8d6c4de 100644
--- a/Documentation/dev-options.rst
+++ b/Documentation/dev-options.rst
@@ -1,5 +1,5 @@
-sparse - extra options for developers
-=====================================
+Extra options for developers
+============================
 
 SYNOPSIS
 --------
diff --git a/Documentation/doc-guide.rst b/Documentation/doc-guide.rst
index 8133cb3a59df..29f39aab360a 100644
--- a/Documentation/doc-guide.rst
+++ b/Documentation/doc-guide.rst
@@ -1,5 +1,5 @@
-How to write sparse documentation
-=================================
+Documentation guide
+===================
 
 Introduction
 ------------
diff --git a/Documentation/types.rst b/Documentation/types.rst
index 272f32a0f4ed..974f9861afef 100644
--- a/Documentation/types.rst
+++ b/Documentation/types.rst
@@ -1,6 +1,6 @@
-********************
-Sparse's Type System
-********************
+***********
+Type System
+***********
 
 struct symbol is used to represent symbols & types but
 most parts pertaining to the types are in the field 'ctype'.
-- 
2.28.0

[PATCH 7/7] doc: add links to some external doc

[Luc Van Oostenryck]

One is a LWN article which covers sparse very well, the other
is a pdf giving a short overview of sparse.

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

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 4bca8c7e47f3..e29a5643849a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -69,6 +69,11 @@ Bugs can also be reported and tracked via the `Linux kernel's bugzilla for spars
 
    annotations
 
+Some interesting external documentation:
+
+* `Sparse: a look under the hood <https://lwn.net/Articles/689907/>`_
+* `Sparse: a short overview <https://sil2.osadl.org/events/ewc-2019-hands-on/sparse_slides.pdf>`_
+
 .. toctree::
    :caption: Development
    :maxdepth: 1
-- 
2.28.0