Restructure Readthedocs documentation (#3428)

* Restructure Readthedocs documentation Pbench docs (Readthedocs) need some rework, so this is the first step towards documentation efforts. This is just a structural change, this commit does not intend to make content level changes. Changes: - New directory structure. - Copy existing Contributing, Server API doc, getting started, user guide and system design files to new dir - Add support for markdown files(earlier it was only reStructuredText).
distributed-system-analysis · May 23, 2023 · 64449cc · 64449cc
1 parent 49ffc55
commit 64449cc
Show file tree

Hide file tree

Showing 35 changed files with 84 additions and 8 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_build/
diff --git a/docs/Agent/faq.md b/docs/Agent/faq.md
@@ -0,0 +1 @@
+# FAQ
diff --git a/docs/Agent/installation/Ansible_based_installation.md b/docs/Agent/installation/Ansible_based_installation.md
@@ -0,0 +1 @@
+# Ansible based installation
diff --git a/docs/Agent/installation/index.rst b/docs/Agent/installation/index.rst
@@ -0,0 +1,12 @@
+Installation
+=========================
+
+Choose any one of the following approaches to setup `Pbench Agent`
+
+.. toctree::
+   :maxdepth: 2
+
+   pbench-containers
+   rpm_based_installation
+   Ansible_based_installation
+
diff --git a/docs/Agent/installation/pbench-containers.md b/docs/Agent/installation/pbench-containers.md
@@ -0,0 +1,2 @@
+# Pbench containers
+
diff --git a/docs/Agent/installation/rpm_based_installation.md b/docs/Agent/installation/rpm_based_installation.md
@@ -0,0 +1 @@
+# RPM based installation
diff --git a/docs/guides/UserGuide.rst → docs/Agent/user-guide/UserGuide.rst b/docs/guides/UserGuide.rst → docs/Agent/user-guide/UserGuide.rst
@@ -4,7 +4,6 @@ User Guide
 ##############
 
 .. contents::
-
 What is Pbench?
 ****************
 

diff --git a/docs/GETTING_STARTED.md → docs/Agent/user-guide/getting_started.md b/docs/GETTING_STARTED.md → docs/Agent/user-guide/getting_started.md
diff --git a/docs/Agent/user-guide/index.rst b/docs/Agent/user-guide/index.rst
@@ -0,0 +1,9 @@
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   getting_started
+   UserGuide
+   man_page
diff --git a/docs/Agent/user-guide/man_page.md b/docs/Agent/user-guide/man_page.md
@@ -0,0 +1 @@
+# Man Page
diff --git a/docs/Dashboard/faq.md b/docs/Dashboard/faq.md
@@ -0,0 +1 @@
+# FAQ
diff --git a/docs/Dashboard/user_guide.md b/docs/Dashboard/user_guide.md
@@ -0,0 +1 @@
+# Pbench Dashboard User Guide
diff --git a/docs/CONTRIBUTING.md → docs/Developers/contributing.md b/docs/CONTRIBUTING.md → docs/Developers/contributing.md
diff --git a/docs/ReverseProxyPbenchServer.uml-seq.md → ...esign/ReverseProxyPbenchServer.uml-seq.md b/docs/ReverseProxyPbenchServer.uml-seq.md → ...esign/ReverseProxyPbenchServer.uml-seq.md
diff --git a/docs/pbench-agent.uml-seq.md → ...ers/system design/pbench-agent.uml-seq.md b/docs/pbench-agent.uml-seq.md → ...ers/system design/pbench-agent.uml-seq.md
diff --git a/...ntication/third_party_token_management.md → ...ntication/third_party_token_management.md b/...ntication/third_party_token_management.md → ...ntication/third_party_token_management.md
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,14 @@
+# Documentation
+
+PBench website [gh-pages](https://distributed-system-analysis.github.io/pbench)
+PBench readthedocs [self hosted](https://distributed-system-analysis.github.io/pbench/docs) and [readthedoc instance](https://pbench.readthedocs.io) 
+
+This dir has all the pbench documentation(api, user guide, commands, gh-pages, etc).
+Pbench website is hosted on gh-pages and readthedocs pages(`/docs`) are also hosted along with it.
+
+## Readthedocs setup
+
+`$ pip3 install -r requirement.txt`
+`$ make clean`
+`$ make html`
+> **Note:**  Above command will build your readthedocs page in `_build/html` dir.
diff --git a/docs/API/README.md → docs/Server/API/README.md b/docs/API/README.md → docs/Server/API/README.md
diff --git a/docs/API/V1/README.md → docs/Server/API/V1/README.md b/docs/API/V1/README.md → docs/Server/API/V1/README.md
diff --git a/docs/API/V1/contents.md → docs/Server/API/V1/contents.md b/docs/API/V1/contents.md → docs/Server/API/V1/contents.md
diff --git a/docs/API/V1/delete.md → docs/Server/API/V1/delete.md b/docs/API/V1/delete.md → docs/Server/API/V1/delete.md
diff --git a/docs/API/V1/detail.md → docs/Server/API/V1/detail.md b/docs/API/V1/detail.md → docs/Server/API/V1/detail.md
diff --git a/docs/API/V1/endpoints.md → docs/Server/API/V1/endpoints.md b/docs/API/V1/endpoints.md → docs/Server/API/V1/endpoints.md
diff --git a/docs/API/V1/inventory.md → docs/Server/API/V1/inventory.md b/docs/API/V1/inventory.md → docs/Server/API/V1/inventory.md
diff --git a/docs/API/V1/list.md → docs/Server/API/V1/list.md b/docs/API/V1/list.md → docs/Server/API/V1/list.md
diff --git a/docs/API/V1/server_audit.md → docs/Server/API/V1/server_audit.md b/docs/API/V1/server_audit.md → docs/Server/API/V1/server_audit.md
diff --git a/docs/API/V1/server_settings.md → docs/Server/API/V1/server_settings.md b/docs/API/V1/server_settings.md → docs/Server/API/V1/server_settings.md
diff --git a/docs/API/V1/update.md → docs/Server/API/V1/update.md b/docs/API/V1/update.md → docs/Server/API/V1/update.md
diff --git a/docs/API/V1/upload.md → docs/Server/API/V1/upload.md b/docs/API/V1/upload.md → docs/Server/API/V1/upload.md
diff --git a/docs/API/access_model.md → docs/Server/API/access_model.md b/docs/API/access_model.md → docs/Server/API/access_model.md
diff --git a/docs/API/metadata.md → docs/Server/API/metadata.md b/docs/API/metadata.md → docs/Server/API/metadata.md
@@ -1,3 +1,5 @@
+# Metadata
+
 ## Dataset metadata
 
 A dataset is referenced by a formal resource ID, and also has a resource name

diff --git a/docs/Server/faq.md b/docs/Server/faq.md
@@ -0,0 +1 @@
+# FAQ
diff --git a/docs/conf.py b/docs/conf.py
@@ -42,6 +42,7 @@
 extensions = [
     "sphinx.ext.autosectionlabel",
     "sphinx_design",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -51,7 +52,13 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "restructuredtext",
+    ".md": "markdown",
+}
+
+myst_enable_extensions = ["colon_fence"]
 
 # The master toctree document.
 master_doc = "index"

diff --git a/docs/index.rst b/docs/index.rst
@@ -4,9 +4,9 @@
    contain the root `toctree` directive.
 
 Pbench
-########
+======
 
-A Benchmarking and Performance Analysis Framework
+Pbench is a Benchmarking and Performance Analysis Framework.
 
 .. dropdown:: Pbench Agent
    :animate: fade-in-slide-down
@@ -27,13 +27,35 @@ A Benchmarking and Performance Analysis Framework
     by the Agent and indexed by the Server.
 
 
-**Table of Contents**
+.. toctree::
+   :maxdepth: 4
+   :hidden:
+   :caption: Pbench Agent 
+
+   Agent/installation/index
+   Agent/user-guide/index
+   Agent/faq
 
-* :doc:`guides/UserGuide`
+.. toctree::
+   :maxdepth: 4
+   :hidden:
+   :caption: Pbench Server
 
+   Server/API/README
+   Server/FAQ/faq
+
 .. toctree::
-   :caption: Pbench-agent
+   :maxdepth: 4
    :hidden:
+   :caption: Pbench Dashboard
+
+   Dashboard/user_guide
+   Dashboard/faq
 
-   guides/UserGuide
+.. toctree::
+   :maxdepth: 4
+   :hidden:
+   :caption: Pbench Developer Guidelines
+
+   Developers/contributing
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1,3 @@
 sphinx-design
 sphinx-rtd-theme
+myst-parser