Restructure documentation index

docs/_static/theme_overrides.css

@@ -0,0 +1,73 @@
+/* this is the container for the pages */
+.wy-nav-content {
+    max-width: 100%;
+    padding: 0px 40px 0px 0px;
+    margin-top: 0px;
+}
+
+.wy-nav-content-wrap {
+    border-right: solid 1px;
+}
+
+div.rst-content {
+    max-width: 1300px;
+    border: 0;
+    padding: 10px 80px 10px 80px;
+    margin-left: 50px;
+}
+
+@media (max-width: 768px) {
+    div.rst-content {
+        max-width: 1300px;
+        border: 0;
+        padding: 0px 10px 10px 10px;
+        margin-left: 0px;
+    }
+}
+
+.row {
+    clear: both;
+}
+
+.column img {
+    border: 1px solid gray;
+}
+
+@media only screen and (min-width: 1000px),
+only screen and (min-width: 500px) and (max-width: 768px) {
+
+    .column {
+        padding-left: 5px;
+        padding-right: 5px;
+        float: left;
+    }
+
+    .column3 {
+        width: calc(33.3% - 10px);
+    }
+
+    .column2 {
+        width: calc(50% - 11px);
+        position: relative;
+    }
+
+    .column2:before {
+        padding-top: 61.8%;
+        content: "";
+        display: block;
+        float: left;
+    }
+
+    .top-left {
+        border-right: 1px solid var(--color-background-border);
+        border-bottom: 1px solid var(--color-background-border);
+    }
+
+    .top-right {
+        border-bottom: 1px solid var(--color-background-border);
+    }
+
+    .bottom-left {
+        border-right: 1px solid var(--color-background-border);
+    }
+}

docs/conf.py

@@ -65,6 +65,20 @@
 
 # -- Options for HTML output -------------------------------------------------
 
+html_static_path = ["_static"]
+
+html_context = {
+    "display_github": True,
+    "github_user": "aboutcode-org",
+    "github_repo": "scancode.io",
+    "github_version": "main",  # branch
+    "conf_py_path": "/docs/",  # path in the checkout to the docs root
+}
+
+html_css_files = [
+    "theme_overrides.css",
+]
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "sphinx_rtd_theme"

docs/improve-docs.rst

@@ -0,0 +1,8 @@
+Something Missing?
+------------------
+
+If something is missing in the documentation or if you found some part confusing, please file
+an `issue <https://github.com/aboutcode-org/scancode.io/issues/new>`_ with your suggestions for
+improvement. Use the ``documentation`` issue label.
+
+Your help makes ScanCode docs better, we love hearing from you!

docs/index.rst

@@ -1,20 +1,104 @@
 ScanCode.io Documentation
 =========================
 
-Welcome! This is your starting point for everything ScanCode.io.
+ScanCode.io provides a Web UI and API to run and review complex scans in rich scripted
+pipelines, on different kinds of containers, docker images, package archives, manifests
+etc, to get information on licenses, copyrights, sources, and vulnerabilities.
 
-In this documentation, you’ll find:
+ScanCode.io provides an easy-to-use front-end to ScanCode Toolkit and other AboutCode
+projects.The flexible pipeline technology supports advanced scanning tasks such as
+container scanning and deploy-to-develop analysis. You can run ScanCode.io in a Docker
+container or install it on a Linux server. It provides full support for generating and
+consuming CycloneDX and SPDX SBOMs.
 
-- A **QuickStart guide** to run your first scan
-- An **overview** of what ScanCode.io is and what it can do
-- **Installation instructions** for full access
-- Step-by-step **tutorials** to dive deeper
-- In-depth **reference docs** on concepts, pipelines, configuration, and APIs
-- Guides on how to **contribute** to the project and community
+Documentation overview
+~~~~~~~~~~~~~~~~~~~~~~
+
+The overview below outlines how the documentation is structured
+to help you know where to look for certain things.
+
+.. rst-class:: clearfix row
+
+.. rst-class:: column column2 top-left
+
+Getting started
+~~~~~~~~~~~~~~~~~~~~~~
+
+Start here if you are new to ScanCode.
+
+- :ref:`quickstart`
+- :ref:`introduction`
+- :ref:`installation`
+- :ref:`contributing`
+- :ref:`user_interface`
+
+.. rst-class:: column column2 top-right
+
+Tutorials
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Learn via practical step-by-step guides.
+
+- :ref:`tutorial_web_ui_analyze_docker_image`
+- :ref:`tutorial_web_ui_review_scan_results`
+- :ref:`tutorial_cli_analyze_docker_image`
+- :ref:`tutorial_api_analyze_package_archive`
+- :ref:`tutorial_license_policies`
+- :ref:`tutorial_vulnerablecode_integration`
+- :ref:`tutorial_web_ui_symbol_and_string_collection`
+- :ref:`tutorial_cli_end_to_end_scanning_to_dejacode`
+
+.. rst-class:: column column2 bottom-left
+
+Reference Docs
+~~~~~~~~~~~~~~~~~~
+
+Reference documentation for scancode features and customizations.
+
+- :ref:`built_in_pipelines`
+- :ref:`custom_pipelines`
+- :ref:`project_configuration`
+- :ref:`inputs`
+- :ref:`output_files`
+- :ref:`command_line_interface`
+- :ref:`rest_api`
+- :ref:`policies`
+- :ref:`data_model`
+- :ref:`automation`
+- :ref:`webhooks`
+- :ref:`scancodeio_settings`
+- :ref:`recognized_distros_os_images`
+
+.. rst-class:: column column2 bottom-right
+
+Explanations
+~~~~~~~~~~~~~~~~~~
+
+Consult the reference to understand ScanCode.io concepts.
+
+- :ref:`scanpipe_concepts`
+- :ref:`scanpipe_pipes`
+
+.. rst-class:: row clearfix
+
+Misc
+~~~~~~~~~~~~~~~
+
+- :ref:`faq`
+- :ref:`changelog`
+
+.. include:: improve-docs.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
 
 .. toctree::
     :maxdepth: 2
-    :caption: Getting Started
+    :hidden:
 
     quickstart
     introduction
@@ -23,11 +107,6 @@ In this documentation, you’ll find:
     faq
     contributing
     changelog
-
-.. toctree::
-    :maxdepth: 2
-    :caption: Tutorials
-
     tutorial_web_ui_analyze_docker_image
     tutorial_web_ui_review_scan_results
     tutorial_cli_analyze_docker_image
@@ -37,11 +116,6 @@ In this documentation, you’ll find:
     tutorial_vulnerablecode_integration
     tutorial_web_ui_symbol_and_string_collection
     tutorial_cli_end_to_end_scanning_to_dejacode
-
-.. toctree::
-    :maxdepth: 2
-    :caption: Reference
-
     scanpipe-concepts
     built-in-pipelines
     custom-pipelines
@@ -57,9 +131,3 @@ In this documentation, you’ll find:
     webhooks
     application-settings
     distros-os-images
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`