From 64449cc382fcfe27c706c9fc5c14c3ba033f30af Mon Sep 17 00:00:00 2001 From: Vishal Vijayraghavan Date: Tue, 23 May 2023 16:48:46 +0530 Subject: [PATCH] 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). --- docs/.gitignore | 1 + docs/Agent/faq.md | 1 + .../Ansible_based_installation.md | 1 + docs/Agent/installation/index.rst | 12 +++++++ docs/Agent/installation/pbench-containers.md | 2 ++ .../installation/rpm_based_installation.md | 1 + .../user-guide}/UserGuide.rst | 1 - .../user-guide/getting_started.md} | 0 docs/Agent/user-guide/index.rst | 9 +++++ docs/Agent/user-guide/man_page.md | 1 + docs/Dashboard/faq.md | 1 + docs/Dashboard/user_guide.md | 1 + .../contributing.md} | 0 .../ReverseProxyPbenchServer.uml-seq.md | 0 .../system design}/pbench-agent.uml-seq.md | 0 .../third_party_token_management.md | 0 docs/README.md | 14 ++++++++ docs/{ => Server}/API/README.md | 0 docs/{ => Server}/API/V1/README.md | 0 docs/{ => Server}/API/V1/contents.md | 0 docs/{ => Server}/API/V1/delete.md | 0 docs/{ => Server}/API/V1/detail.md | 0 docs/{ => Server}/API/V1/endpoints.md | 0 docs/{ => Server}/API/V1/inventory.md | 0 docs/{ => Server}/API/V1/list.md | 0 docs/{ => Server}/API/V1/server_audit.md | 0 docs/{ => Server}/API/V1/server_settings.md | 0 docs/{ => Server}/API/V1/update.md | 0 docs/{ => Server}/API/V1/upload.md | 0 docs/{ => Server}/API/access_model.md | 0 docs/{ => Server}/API/metadata.md | 2 ++ docs/Server/faq.md | 1 + docs/conf.py | 9 ++++- docs/index.rst | 34 +++++++++++++++---- docs/requirements.txt | 1 + 35 files changed, 84 insertions(+), 8 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Agent/faq.md create mode 100644 docs/Agent/installation/Ansible_based_installation.md create mode 100644 docs/Agent/installation/index.rst create mode 100644 docs/Agent/installation/pbench-containers.md create mode 100644 docs/Agent/installation/rpm_based_installation.md rename docs/{guides => Agent/user-guide}/UserGuide.rst (99%) rename docs/{GETTING_STARTED.md => Agent/user-guide/getting_started.md} (100%) create mode 100644 docs/Agent/user-guide/index.rst create mode 100644 docs/Agent/user-guide/man_page.md create mode 100644 docs/Dashboard/faq.md create mode 100644 docs/Dashboard/user_guide.md rename docs/{CONTRIBUTING.md => Developers/contributing.md} (100%) rename docs/{ => Developers/system design}/ReverseProxyPbenchServer.uml-seq.md (100%) rename docs/{ => Developers/system design}/pbench-agent.uml-seq.md (100%) rename docs/{ => Developers/system design}/user_authentication/third_party_token_management.md (100%) create mode 100644 docs/README.md rename docs/{ => Server}/API/README.md (100%) rename docs/{ => Server}/API/V1/README.md (100%) rename docs/{ => Server}/API/V1/contents.md (100%) rename docs/{ => Server}/API/V1/delete.md (100%) rename docs/{ => Server}/API/V1/detail.md (100%) rename docs/{ => Server}/API/V1/endpoints.md (100%) rename docs/{ => Server}/API/V1/inventory.md (100%) rename docs/{ => Server}/API/V1/list.md (100%) rename docs/{ => Server}/API/V1/server_audit.md (100%) rename docs/{ => Server}/API/V1/server_settings.md (100%) rename docs/{ => Server}/API/V1/update.md (100%) rename docs/{ => Server}/API/V1/upload.md (100%) rename docs/{ => Server}/API/access_model.md (100%) rename docs/{ => Server}/API/metadata.md (99%) create mode 100644 docs/Server/faq.md diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..c6a151b325 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build/ \ No newline at end of file diff --git a/docs/Agent/faq.md b/docs/Agent/faq.md new file mode 100644 index 0000000000..4514b4c106 --- /dev/null +++ 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 new file mode 100644 index 0000000000..e71ed95fe2 --- /dev/null +++ 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 new file mode 100644 index 0000000000..6941c4e8d1 --- /dev/null +++ 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 new file mode 100644 index 0000000000..93033f4fd7 --- /dev/null +++ b/docs/Agent/installation/pbench-containers.md @@ -0,0 +1,2 @@ +# Pbench containers + \ No newline at end of file diff --git a/docs/Agent/installation/rpm_based_installation.md b/docs/Agent/installation/rpm_based_installation.md new file mode 100644 index 0000000000..0454b7723c --- /dev/null +++ b/docs/Agent/installation/rpm_based_installation.md @@ -0,0 +1 @@ +# RPM based installation diff --git a/docs/guides/UserGuide.rst b/docs/Agent/user-guide/UserGuide.rst similarity index 99% rename from docs/guides/UserGuide.rst rename to docs/Agent/user-guide/UserGuide.rst index 845298fc7b..d508bb4125 100644 --- a/docs/guides/UserGuide.rst +++ b/docs/Agent/user-guide/UserGuide.rst @@ -4,7 +4,6 @@ User Guide ############## .. contents:: - What is Pbench? **************** diff --git a/docs/GETTING_STARTED.md b/docs/Agent/user-guide/getting_started.md similarity index 100% rename from docs/GETTING_STARTED.md rename to docs/Agent/user-guide/getting_started.md diff --git a/docs/Agent/user-guide/index.rst b/docs/Agent/user-guide/index.rst new file mode 100644 index 0000000000..9f9a669fb4 --- /dev/null +++ b/docs/Agent/user-guide/index.rst @@ -0,0 +1,9 @@ +User Guide +========== + +.. toctree:: + :maxdepth: 2 + + getting_started + UserGuide + man_page \ No newline at end of file diff --git a/docs/Agent/user-guide/man_page.md b/docs/Agent/user-guide/man_page.md new file mode 100644 index 0000000000..ffb00186d7 --- /dev/null +++ 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 new file mode 100644 index 0000000000..4514b4c106 --- /dev/null +++ b/docs/Dashboard/faq.md @@ -0,0 +1 @@ +# FAQ diff --git a/docs/Dashboard/user_guide.md b/docs/Dashboard/user_guide.md new file mode 100644 index 0000000000..e210407eba --- /dev/null +++ b/docs/Dashboard/user_guide.md @@ -0,0 +1 @@ +# Pbench Dashboard User Guide diff --git a/docs/CONTRIBUTING.md b/docs/Developers/contributing.md similarity index 100% rename from docs/CONTRIBUTING.md rename to docs/Developers/contributing.md diff --git a/docs/ReverseProxyPbenchServer.uml-seq.md b/docs/Developers/system design/ReverseProxyPbenchServer.uml-seq.md similarity index 100% rename from docs/ReverseProxyPbenchServer.uml-seq.md rename to docs/Developers/system design/ReverseProxyPbenchServer.uml-seq.md diff --git a/docs/pbench-agent.uml-seq.md b/docs/Developers/system design/pbench-agent.uml-seq.md similarity index 100% rename from docs/pbench-agent.uml-seq.md rename to docs/Developers/system design/pbench-agent.uml-seq.md diff --git a/docs/user_authentication/third_party_token_management.md b/docs/Developers/system design/user_authentication/third_party_token_management.md similarity index 100% rename from docs/user_authentication/third_party_token_management.md rename to docs/Developers/system design/user_authentication/third_party_token_management.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..079b117f0f --- /dev/null +++ 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 b/docs/Server/API/README.md similarity index 100% rename from docs/API/README.md rename to docs/Server/API/README.md diff --git a/docs/API/V1/README.md b/docs/Server/API/V1/README.md similarity index 100% rename from docs/API/V1/README.md rename to docs/Server/API/V1/README.md diff --git a/docs/API/V1/contents.md b/docs/Server/API/V1/contents.md similarity index 100% rename from docs/API/V1/contents.md rename to docs/Server/API/V1/contents.md diff --git a/docs/API/V1/delete.md b/docs/Server/API/V1/delete.md similarity index 100% rename from docs/API/V1/delete.md rename to docs/Server/API/V1/delete.md diff --git a/docs/API/V1/detail.md b/docs/Server/API/V1/detail.md similarity index 100% rename from docs/API/V1/detail.md rename to docs/Server/API/V1/detail.md diff --git a/docs/API/V1/endpoints.md b/docs/Server/API/V1/endpoints.md similarity index 100% rename from docs/API/V1/endpoints.md rename to docs/Server/API/V1/endpoints.md diff --git a/docs/API/V1/inventory.md b/docs/Server/API/V1/inventory.md similarity index 100% rename from docs/API/V1/inventory.md rename to docs/Server/API/V1/inventory.md diff --git a/docs/API/V1/list.md b/docs/Server/API/V1/list.md similarity index 100% rename from docs/API/V1/list.md rename to docs/Server/API/V1/list.md diff --git a/docs/API/V1/server_audit.md b/docs/Server/API/V1/server_audit.md similarity index 100% rename from docs/API/V1/server_audit.md rename to docs/Server/API/V1/server_audit.md diff --git a/docs/API/V1/server_settings.md b/docs/Server/API/V1/server_settings.md similarity index 100% rename from docs/API/V1/server_settings.md rename to docs/Server/API/V1/server_settings.md diff --git a/docs/API/V1/update.md b/docs/Server/API/V1/update.md similarity index 100% rename from docs/API/V1/update.md rename to docs/Server/API/V1/update.md diff --git a/docs/API/V1/upload.md b/docs/Server/API/V1/upload.md similarity index 100% rename from docs/API/V1/upload.md rename to docs/Server/API/V1/upload.md diff --git a/docs/API/access_model.md b/docs/Server/API/access_model.md similarity index 100% rename from docs/API/access_model.md rename to docs/Server/API/access_model.md diff --git a/docs/API/metadata.md b/docs/Server/API/metadata.md similarity index 99% rename from docs/API/metadata.md rename to docs/Server/API/metadata.md index f7c4e634d2..4ac1c2e9f0 100644 --- a/docs/API/metadata.md +++ b/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 new file mode 100644 index 0000000000..4514b4c106 --- /dev/null +++ b/docs/Server/faq.md @@ -0,0 +1 @@ +# FAQ diff --git a/docs/conf.py b/docs/conf.py index 25997c145c..a33b1d8a0f 100644 --- 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 index dd01296e8e..405cdcc8d3 100644 --- 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 index 3d50b8a3ec..1c2b2e9cf0 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx-design sphinx-rtd-theme +myst-parser \ No newline at end of file