Get back the navigation sidebar on the LLDB website.

This returns the look & feel of the Sphinx-generated LLDB website to
the original pre-Sphinx layout.

Differential Revision: https://reviews.llvm.org/D61913

llvm-svn: 360819

lldb/docs/CMakeLists.txt

@@ -58,6 +58,11 @@ if (LLVM_ENABLE_SPHINX)
   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()

lldb/docs/_static/lldb.css

@@ -1,3 +1,15 @@
+pre {
+  padding: 7px;
+}
+
+div.document {
+  width: 90%;
+}
+
+div.body {
+  max-width: 90%;
+}
+
 table.mapping {
   width: 100%;
 }
@@ -9,18 +21,66 @@ table.mapping td {
 
 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;
+}

lldb/docs/conf.py

@@ -92,12 +92,14 @@
 
 # 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 = []

lldb/docs/index.rst

@@ -16,24 +16,105 @@ 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
@@ -47,11 +128,10 @@ Use & Extension
    use/troubleshooting
    use/architecture
 
-Resources
-=========
-
 .. toctree::
+   :hidden:
    :maxdepth: 1
+   :caption: Resources
 
    resources/download
    resources/source
@@ -60,16 +140,20 @@ Resources
    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>`_
+   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
-==============
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: 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/>

lldb/docs/use/formatting.rst

@@ -1,5 +1,5 @@
-Stack Frame and Thread Format
-=============================
+Frame and Thread Format
+=======================
 
 .. contents::
    :local: