Merge branch 'main' of git.beagleboard.org:docs/docs.beagleboard.io

conf.py

@@ -84,9 +84,14 @@ with open(BBDOCS_BASE  / "VERSION") as f:
 
 release = version
 
-pages_url = ""
-pages_slug = ""
-docs_url = ""
+# Variables here holds default settings
+pages_url = "http://docs.beagleboard.io"
+pages_slug = "latest"
+gitlab_user = "docs"
+gitlab_version = "main"
+gitlab_host = "git.beagleboard.org"
+gitlab_repo = "docs.beagleboard.io"
+docs_url = "https://docs.beagleboard.io/latest/"
 
 # parse pages details from 'PAGES' file
 with open(BBDOCS_BASE  / "PAGES") as f:
@@ -94,6 +99,10 @@ with open(BBDOCS_BASE  / "PAGES") as f:
         (
             r"^PAGES_URL\s*=\s*(\S+)$\n"
             + r"^PAGES_SLUG\s*=\s*(\S+)$\n"
+            + r"^GITLAB_USER\s*=\s*(\S+)$\n"
+            + r"^PROJECT_BRANCH\s*=\s*(\S+)$\n"
+            + r"^GITLAB_HOST\s*=\s*(\S+)$\n"
+            + r"^PROJECT_REPO\s*=\s*(\S+)$\n"
         ),
         f.read(),
         re.MULTILINE,
@@ -102,18 +111,22 @@ with open(BBDOCS_BASE  / "PAGES") as f:
     if not m:
         sys.stderr.write("Warning: Could not extract pages information\n")
     else:
-        url, slug = m.groups(1)
+        url, slug, user, branch, host, repo = m.groups(1)
         slug = "latest" if slug == "main" else slug
         pages_url = url
         pages_slug = slug
+        gitlab_user = user
+        gitlab_version = branch
+        gitlab_host = host
+        gitlab_repo = repo
         docs_url = "/".join((url, slug))
 
 html_context = {
     "display_gitlab": True,
-    "gitlab_host": "git.beagleboard.org",
-    "gitlab_user": "docs",
-    "gitlab_repo": "docs.beagleboard.io",
-    "gitlab_version": "main",
+    "gitlab_host": gitlab_host,
+    "gitlab_user": gitlab_user,
+    "gitlab_repo": gitlab_repo,
+    "gitlab_version": gitlab_version,
     "conf_py_path": "/",
     "show_license": True,
     "pages_url": pages_url,

gitlab-build.sh

@@ -5,6 +5,10 @@ env
 cat << EOF > PAGES
 PAGES_URL =  $CI_PAGES_URL
 PAGES_SLUG = $CI_COMMIT_BRANCH
+GITLAB_USER = $CI_PROJECT_NAMESPACE
+PROJECT_BRANCH = $CI_COMMIT_BRANCH
+GITLAB_HOST = $CI_SERVER_HOST
+PROJECT_REPO = $CI_PROJECT_NAME
 EOF
 
 if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then

index.rst

@@ -46,7 +46,7 @@ from source using appropriate design tools.
 * Check out our latest board at: :ref:`bbai64-home`
 * Find all of our on: :ref:`boards`
 
-.. grid:: 1 1 1 2
+.. grid:: 1 1 2 3
    :margin: 4 4 0 0
    :gutter: 4
 
@@ -143,7 +143,7 @@ from source using appropriate design tools.
 Capes
 ******
 
-.. grid:: 1 1 1 2
+.. grid:: 1 1 2 3
    :margin: 4 4 0 0
    :gutter: 4
 

intro/contribution/index.rst

@@ -88,3 +88,4 @@ Style and usage guidelines
 
    /intro/contribution/git-usage
    /intro/contribution/style
+   /intro/contribution/rst-cheat-sheet

intro/contribution/rst-cheat-sheet.rst

+.. _rst-cheat-sheet:
+
+ReStructuredText Cheat Sheet
+############################
+
+BeagleBoard docs is mostly writted with ReStructuredText (r)
+
+Headings
+*********
+
+For each document we divide sections with headings and in ReStructuredText we can use 
+matching overline and underline to indicate a heading. 
+
+1. Document heading (H1) use ``#``.
+2. First heading (H2) use ``*``.
+3. First heading (H2) use ``=``.
+4. First heading (H2) use ``-``.
+5. First heading (H2) use ``~``.
+
+.. note::
+    You can include only one (H1) ``#`` in a single documentation page.
+
+Make sure the length of your heading symbol is atleast (or 
+more) the lenth of the heading text, for example:
+
+
+.. callout::
+
+    .. code-block:: ReStructuredText
+
+        incorrect H1
+        ##### # <1>
+
+        correct H1
+        ############ # <2>
+    
+    .. annotations::
+
+        <1> length of heading sybol ``#`` is smaller than the content above.
+        <2> Shows the correct way of setting the document title (H1) with ``#``.
+
+    
\ No newline at end of file