Get back the navigation sidebar on the LLDB website

[JDevlieghere]

Summary

This is a little experiment to get back the navigation sidebar on the LLDB website like it used to be: https://web.archive.org/web/20170204135403/http://lldb.llvm.org/

Note that due to a dependency tracking problem you need to

rm -rf tools/lldb/docs/html && ninja docs-lldb-html

to see the updated CSS.

[aprantl]

lldb/docs/_static/lldb.css

27 ↗

(On Diff #199495)

This is copied & pasted from the old static website.

[aprantl]

lldb/docs/index.rst

73 ↗

(On Diff #199495)

This doesn't work yet.

[aprantl]

Make Doxygen links in sidebar work.

[aprantl]

Do you think the fact that sphinx doesn't update the css will be a problem on lldb.llvm.org with the way the script is run? (ninja clean does not delete the html directory either).

[aprantl]

I think I addressed most/all of the outstanding bugs.

[aprantl]

Add more context to the diff.

[aprantl]

More tweaks from Jonas & me.

[JDevlieghere]

Hostile take-over of the patch ;-)

[JDevlieghere]

Fix pre-padding

docs/CMakeLists.txt

else()
   message(STATUS "Could NOT find epydoc")
 endif()
 
 if (LLVM_ENABLE_SPHINX)
   include(AddSphinxTarget)
   if (SPHINX_FOUND)
     if (${SPHINX_OUTPUT_HTML})
       add_sphinx_target(html lldb)
+      # Sphinx does not reliably update the custom CSS files, so force
+      # a clean rebuild of the documentation every time.
+      add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E
+        remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html)
+      add_dependencies(docs-lldb-html clean-lldb-html)
     endif()
   endif()
 endif()

docs/_static/lldb.css

+pre {
+  padding: 7px;
+}
+
+div.document {
+  width: 90%;
+}
+
+div.body {
+  max-width: 90%;
+}
+
 table.mapping {
   width: 100%;
 }
 
 table.mapping td {
   width: 50%;
   padding: 5px;
 }
 
 table.mapping td.hed {
   background: #606060;
-  color: white;
+  color: #fefefe;
   text-align: left;
-  border-bottom: 2px #fff solid;
+  border-bottom: 2px #fefefe solid;
   font-weight: bold;
 }
 
 table.mapping td.header {
-  background: #eee;
+  background: #eeeeee;
 }
 
 table.mapping td.content {
   font-family: monospace;
   padding-bottom: 15px;
 }
 
+div.sphinxsidebar .caption {
+  font-family: Helvetica, Verdana, sans-serif;
+  font-size: 10pt;
+  font-weight:bold;
+  color: #fefefe;
+  background: #606060;
+  margin-bottom: 0;
+  text-transform: uppercase;
+  padding: 7px;
+}
+
+div.sphinxsidebar a,
+div.sphinxsidebar a:hover {
+  border: none;
+}
+
+div.sphinxsidebar li {
+  padding-left:5px;
+  padding-right:5px;
+  border-bottom:1px solid #fefefe;
+}
+
+div.sphinxsidebar li:hover {
+  background: #eeeeee;
+}
+
+div.sphinxsidebar ul {
+  background: #e9e9e9;
+  margin: 0px;
+  padding: 0px;
+}
+
+div.sphinxsidebar ul a {
+  font-family: Helvetica, Verdana, sans-serif;
+  font-size: 8pt;
+  display: block;
+  padding: 5px 0;
+  line-height: 14pt;
+}
+
+div.sphinxsidebar ul li.toctree-l1 > a {
+  font-size: 100%;
+}
+
+div.sphinxsidebar h3 {
+  /* Hide Navigation. */
+  display: none;
+}

docs/conf.py

 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'haiku'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'font_size': '11pt'
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 html_title = 'The LLDB Debugger'
 

docs/index.rst

 
 LLDB is the default debugger in Xcode on macOS and supports debugging C,
 Objective-C and C++ on the desktop and iOS devices and simulator.
 
 All of the code in the LLDB project is available under the standard
 `LLVM License <http://llvm.org/docs/DeveloperPolicy.html#copyright-license-and-patents>`__,
 an open source "BSD-style" license.
 
+Why a New Debugger?
+-------------------
 
-Goals & Status
-==============
+In order to achieve our goals we decided to start with a fresh architecture
+that would support modern multi-threaded programs, handle debugging symbols in
+an efficient manner, use compiler based code knowledge and have plug-in support
+for functionality and extensions. Additionally we want the debugger
+capabilities to be available to other analysis tools, be they scripts or
+compiled programs, without requiring them to be GPL.
+
+Compiler Integration Benefits
+-----------------------------
+
+LLDB currently converts debug information into clang types so that it can
+leverage the clang compiler infrastructure. This allows LLDB to support the
+latest C, C++, Objective-C and Objective-C++ language features and runtimes in
+expressions without having to reimplement any of this functionality. It also
+leverages the compiler to take care of all ABI details when making functions
+calls for expressions, when disassembling instructions and extracting
+instruction details, and much more.
+
+The major benefits include:
+
+- Up to date language support for C, C++, Objective-C
+- Multi-line expressions that can declare local variables and types
+- Utilize the JIT for expressions when supported
+- Evaluate expression Intermediate Representation (IR) when JIT can't be used
+
+Reusability
+-----------
+
+The LLDB debugger APIs are exposed as a C++ object oriented interface in a
+shared library. The lldb command line tool links to, and uses this public API.
+On macOS the shared library is exposed as a framework named LLDB.framework,
+and unix systems expose it as lldb.so. The entire API is also then exposed
+through Python script bindings which allow the API to be used within the LLDB
+embedded script interpreter, and also in any python script that loads the
+lldb.py module in standard python script files. See the Python Reference page
+for more details on how and where Python can be used with the LLDB API.
+
+Sharing the LLDB API allows LLDB to not only be used for debugging, but also
+for symbolication, disassembly, object and symbol file introspection, and much
+more.
+
+Platform Support
+----------------
+
+LLDB is known to work on the following platforms, but ports to new platforms
+are welcome:
+
+* macOS desktop user space debugging for i386 and x86-64
+* iOS simulator debugging on i386
+* iOS device debugging on ARM
+* Linux local user-space debugging for i386, x86-64 and PPC64le
+* FreeBSD local user-space debugging for i386 and x86-64
+* Windows local user-space debugging for i386 (*)
+
+(*) Support for Windows is under active development. Basic functionality is
+expected to work, with functionality improving rapidly.
+
+Get Involved
+------------
+
+To check out the code, use:
+
+svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb
+
+Note that LLDB generally builds from top-of-trunk
+
+* On macOS with Xcode
+* On Linux and FreeBSD (with clang and libstdc++/libc++)
+* On NetBSD (with GCC and clang and libstdc++/libc++)
+* On Windows with VS 2012 or higher using CMake
+
+See the LLDB Build Page for platform-specific build instructions.
+
+Discussions about LLDB should go to the `lldb-dev
+<http://lists.llvm.org/mailman/listinfo/lldb-dev>`__ mailing list. Commit
+messages for the lldb SVN module are automatically sent to the `lldb-commits
+<http://lists.llvm.org/mailman/listinfo/lldb-commits>`__ mailing list , and
+this is also the preferred mailing list for patch submissions.
+
+See the Projects page if you are looking for some interesting areas to
+contribute to lldb.
 
 .. toctree::
+   :hidden:
    :maxdepth: 1
+   :caption: Goals & Status
 
-   status/about
    status/goals
    status/features
    status/status
    status/projects
 
-Use & Extension
-===============
-
 .. toctree::
+   :hidden:
    :maxdepth: 1
+   :caption: Use & Extension
 
    use/tutorial
    use/map
    use/formatting
    use/variable
    use/symbolication
    use/symbols
    use/python
    use/python-reference
    use/remote
    use/troubleshooting
    use/architecture
 
-Resources
-=========
-
 .. toctree::
+   :hidden:
    :maxdepth: 1
+   :caption: Resources
 
    resources/download
    resources/source
    resources/build
    resources/test
    resources/bots
    resources/sbapi
 
-API Documentation
-=================
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: API Documentation
+
+   Public Python API Reference <https://lldb.llvm.org/python_reference/index.html>
+   Public C++ API Reference <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
+   Private C++ Reference <https://lldb.llvm.org/cpp_reference/index.html>
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: External Links
 
-* `Public Python API Reference <https://lldb.llvm.org/python_reference/index.html>`_
-* `Public C++ API Reference <https://lldb.llvm.org/cpp_reference/namespacelldb.html>`_
-* `Private C++ Reference <https://lldb.llvm.org/cpp_reference/index.html>`_
-
-External Links
-==============
-
-* `Source Code <http://llvm.org/viewvc/llvm-project/lldb/trunk/>`_
-* `Code Reviews <https://reviews.llvm.org>`_
-* `Bug Reports <https://bugs.llvm.org/>`_
+   Source Code <http://llvm.org/viewvc/llvm-project/lldb/trunk/>
+   Code Reviews <https://reviews.llvm.org>
+   Bug Reports <https://bugs.llvm.org/>

docs/status/about.rst

-About
-=====
-
-.. contents::
-   :local:
-
-Why a New Debugger?
--------------------
-
-In order to achieve our goals we decided to start with a fresh architecture
-that would support modern multi-threaded programs, handle debugging symbols in
-an efficient manner, use compiler based code knowledge and have plug-in support
-for functionality and extensions. Additionally we want the debugger
-capabilities to be available to other analysis tools, be they scripts or
-compiled programs, without requiring them to be GPL.
-
-Compiler Integration Benefits
------------------------------
-
-LLDB currently converts debug information into clang types so that it can
-leverage the clang compiler infrastructure. This allows LLDB to support the
-latest C, C++, Objective-C and Objective-C++ language features and runtimes in
-expressions without having to reimplement any of this functionality. It also
-leverages the compiler to take care of all ABI details when making functions
-calls for expressions, when disassembling instructions and extracting
-instruction details, and much more.
-
-The major benefits include:
-
-- Up to date language support for C, C++, Objective-C
-- Multi-line expressions that can declare local variables and types
-- Utilize the JIT for expressions when supported
-- Evaluate expression Intermediate Representation (IR) when JIT can't be used
-
-Reusability
------------
-
-The LLDB debugger APIs are exposed as a C++ object oriented interface in a
-shared library. The lldb command line tool links to, and uses this public API.
-On macOS the shared library is exposed as a framework named LLDB.framework,
-and unix systems expose it as lldb.so. The entire API is also then exposed
-through Python script bindings which allow the API to be used within the LLDB
-embedded script interpreter, and also in any python script that loads the
-lldb.py module in standard python script files. See the Python Reference page
-for more details on how and where Python can be used with the LLDB API.
-
-Sharing the LLDB API allows LLDB to not only be used for debugging, but also
-for symbolication, disassembly, object and symbol file introspection, and much
-more.
-
-Platform Support
-----------------
-
-LLDB is known to work on the following platforms, but ports to new platforms
-are welcome:
-
-* macOS desktop user space debugging for i386 and x86-64
-* iOS simulator debugging on i386
-* iOS device debugging on ARM
-* Linux local user-space debugging for i386, x86-64 and PPC64le
-* FreeBSD local user-space debugging for i386 and x86-64
-* Windows local user-space debugging for i386 (*)
-
-(*) Support for Windows is under active development. Basic functionality is
-expected to work, with functionality improving rapidly.
-
-Get Involved
-------------
-
-To check out the code, use:
-
-svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb
-
-Note that LLDB generally builds from top-of-trunk
-
-* On macOS with Xcode
-* On Linux and FreeBSD (with clang and libstdc++/libc++)
-* On NetBSD (with GCC and clang and libstdc++/libc++)
-* On Windows with VS 2012 or higher using CMake
-
-See the LLDB Build Page for platform-specific build instructions.
-
-Discussions about LLDB should go to the `lldb-dev
-<http://lists.llvm.org/mailman/listinfo/lldb-dev>`__ mailing list. Commit
-messages for the lldb SVN module are automatically sent to the `lldb-commits
-<http://lists.llvm.org/mailman/listinfo/lldb-commits>`__ mailing list , and
-this is also the preferred mailing list for patch submissions.
-
-See the Projects page if you are looking for some interesting areas to
-contribute to lldb.

docs/use/formatting.rst

-Stack Frame and Thread Format
-=============================
+Frame and Thread Format
+=======================
 
 .. contents::
    :local:
 
 LLDB has a facility to allow users to define the format of the information that
 generates the descriptions for threads and stack frames. Typically when your
 program stops at a breakpoint you will get two lines that describes why your
 thread stopped and where: