source: Refactor content and configuration

Fix unappealing documentation.
Add CSS for unappealing toctree.
Seperate the heading in various guides properly.
Use snake case convertion for file names.
Remove orphaned documents.
Populate linux guides.
Add markdown linter config.

Change-Id: Id88b0f6e5ba4a6c1a5f814ef0877dd47b3934db5
Signed-off-by: UtsavBalar1231 <utsavbalar1231@gmail.com>

.markdownlint.json

@@ -0,0 +1,9 @@
+{
+  "default": true,
+  "MD013": {
+    "line_length": 120
+  },
+  "MD033": false,
+  "MD041": false,
+  "MD051": false
+}

Pipfile

@@ -10,6 +10,8 @@ breathe = "*"
 myst-parser = "*"
 sphinx = "*"
 sphinxawesome_theme = "*"
+sphinx-togglebutton = "*"
+sphinx-design = "*"
 
 [requires]
 python_version = "3"

source/_static/custom.css

@@ -0,0 +1,13 @@
+.contents .caption,
+.contents .topic-title,
+.toctree-wrapper .caption,
+.toctree-wrapper .topic-title {
+  font-weight: 600;
+  font-size: 1.5rem;
+  padding-top: 1.5rem;
+}
+
+#content ul:not(.search) p,
+#content ul:not(.search) > li {
+  margin-top: 0.9rem;
+}

source/conf.py

@@ -1,92 +1,75 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+# Copyright (c) 2023 Vicharak Computers LLP
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-from sphinx.writers.html import HTMLTranslator
-from docutils import nodes
-from docutils.nodes import Element
 import os
 import sys
+from datetime import date
 
 sys.path.insert(0, os.path.abspath("_themes"))
 
-project = 'Vicharak'
-copyright = '2023, Vicharak Computers LLP'
-author = 'Vicharak'
+# General information about the project.
+project = "Vicharak"
+author = "Vicharak Computers LLP"
+copyright = f"{date.today().year}, {author}"
 version = "0.1"
 
-html_theme = 'sphinxawesome_theme'
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = ['breathe', 'myst_parser']
-source_suffix = ['.rst', '.md']
-
-templates_path = ['_templates']
-exclude_patterns = []
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-# -- Documentation for adding theme to local directory
-# https://sphinxawesome.xyz/how-to/add/
-
-
-html_static_path = ['_static']
+# Extensions
+extensions = [
+    "breathe",
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_design",
+    "sphinx_togglebutton",
+    "sphinxawesome_theme",
+]
+
+# Enable colon fence for code blocks
+myst_enable_extensions = [
+    "attrs_block",
+    # Enable inline attribute parsing
+    "attrs_inline",
+    # Enable code fences using ::: delimiters
+    "colon_fence",
+    # Enable definition lists
+    "deflist",
+    # Automatically convert standard quotations
+    # to their opening/closing variants
+    "smartquotes",
+    # Enable strikethrough
+    "strikethrough",
+    # Add check-boxes to the start of list items
+    "tasklist",
+]
+
+suppress_warnings = ["myst.header"]
+
+# Source file parsers
+source_suffix = [".rst", ".md"]
+
+# Set templates and exclude patterns
+templates_path = ["_templates"]
+exclude_patterns = ["build"]
+
+# HTML settings
+html_theme = "sphinxawesome_theme"
+html_static_path = ["_static"]
 html_title = "Vicharak"
-# html_theme_path = ["_themes"]
-# exclude_patterns = ["_themes"]
-
-
-class PatchedHTMLTranslator(HTMLTranslator):
-
-    def visit_reference(self, node: Element) -> None:
-        atts = {'class': 'reference'}
-        if node.get('internal') or 'refuri' not in node:
-            atts['class'] += ' internal'
-        else:
-            atts['class'] += ' external'
-            # ---------------------------------------------------------
-            # Customize behavior (open in new tab, secure linking site)
-            atts['target'] = '_blank'
-            atts['rel'] = 'noopener noreferrer'
-            # ---------------------------------------------------------
-        if 'refuri' in node:
-            atts['href'] = node['refuri'] or '#'
-            if self.settings.cloak_email_addresses and atts['href'].startswith('mailto:'):
-                atts['href'] = self.cloak_mailto(atts['href'])
-                self.in_mailto = True
-        else:
-            assert 'refid' in node, \
-                   'References must have "refuri" or "refid" attribute.'
-            atts['href'] = '#' + node['refid']
-        if not isinstance(node.parent, nodes.TextElement):
-            assert len(node) == 1 and isinstance(node[0], nodes.image)
-            atts['class'] += ' image-reference'
-        if 'reftitle' in node:
-            atts['title'] = node['reftitle']
-        if 'target' in node:
-            atts['target'] = node['target']
-        self.body.append(self.starttag(node, 'a', '', **atts))
-
-        if node.get('secnumber'):
-            self.body.append(('%s' + self.secnumber_suffix) %
-                             '.'.join(map(str, node['secnumber'])))
-
-
-def setup(app):
-    app.set_translator('html', PatchedHTMLTranslator)
-
-
+# CSS files to include
+html_css_files = [
+    "custom.css",
+]
+# Theme options
 html_theme_options = {
+    # sphinxawesome_theme options
     "logo_light": "_static/vicharak-logo-light.svg",
-    "logo_dark": "_static/vicharak-logo-dark.svg"
+    "logo_dark": "_static/vicharak-logo-dark.svg",
+    "show_breadcrumbs": True,
 }
 
+# Breathe extension settings
 breathe_projects = {"drm_fpga_write": os.getcwd() + "/../xml/"}
 breathe_default_project = "drm_fpga_write"

source/contributing.rst

@@ -0,0 +1,4 @@
+:orphan:
+
+Contribution
+============

source/downloads.rst

@@ -0,0 +1,31 @@
+.. _downloads:
+
+Vaaman Downloads
+================
+
+**Datasheets**
+    `Rockchip RK3399 Datasheet <https://www.rockchip.fr/RK3399%20datasheet%20V1.8.pdf>`_
+
+    `Efinix Trion T120 Datasheet <https://www.efinixinc.com/docs/trion120-ds-v3.4.pdf>`_
+
+    `Rockchip RK3399 TRM V1.3 Part1 <https://rockchip.fr/Rockchip%20RK3399%20TRM%20V1.3%20Part1.pdf>`_
+
+    `Rockchip RK3399 TRM V1.3 Part2 <https://rockchip.fr/Rockchip%20RK3399%20TRM%20V1.3%20Part2.pdf>`_
+
+    `Rockchip RK3399 TRM V1.4 Part1 <https://opensource.rock-chips.com/images/e/ee/Rockchip_RK3399TRM_V1.4_Part1-20170408.pdf>`_
+
+
+**Vaaman Pinouts Guide**
+    `Download Pinouts <_static/Vaaman0.3_Pinout_Guide_Rev0.1.pdf>`_
+
+    `RK3399 GPIO Numbers Counts <_static/RK3399_GPIO_NUMBERS_Rev0.1.xlsx>`_
+
+**Mechanical Information**
+    Dimensions: `85mm x 85mm`
+
+    Weight: --- grams
+
+    Mounting holes: 4x M2.5 holes for easy installation
+
+**Step File (Compression: 7z)**
+    `Download Vaaman 3D File <_static/Vaaman_3D_file_V0.3.step.7z>`_

source/drm_fpga_write_api.rst

@@ -1,5 +1,7 @@
 .. _drm_fpga_write_api:
 
+:orphan:
+
 .. toctree::
    :glob:
 

source/get-help.rst → source/getting-help.rst

@@ -1,9 +1,9 @@
-.. _get-help:
+.. _getting-help:
 
-Get Help
-=========
+Getting Help
+============
 
-- instructions on how and where to get help
+- Instructions on how and where to get help
 
 * Default template for issues/questions