Docs: Convert current pbench MarkDown content to readthedocs and reStructuredText format #1730

haoweiqiu · 2020-07-23T02:00:36Z

This PR converts current pbench MarkDown content to readthedocs and reStructuredText format.
The ReadtheDocs link is: https://pbench-docs.readthedocs.io/

portante · 2020-07-27T23:52:57Z

Thanks @haoweiqiu! I'll review soon.

portante · 2020-07-27T23:59:02Z

Can you also consider the gh-pages branch content? Though we are looking to merge #1586 soon.

haoweiqiu · 2020-07-28T21:56:18Z

@portante Thank you very much for the comment! I'll look into #1586 and modify Read the Docs.

dbutenhof

Just skimmed this; comments and questions on content and formatting.

Maybe I'm unclear on the context of this review, but I see missing "pbench-" prefixes on tools, jumbled sets of command lines without line breaks, and odd sample output including Pbench debug statements. Just a few examples are marked in this review. I'll read more later.

dbutenhof · 2020-09-03T11:46:54Z

docs/CONTRIBUTING.rst

+The first step is to install the necessary dependencies that are
+required to run on the system:
+
+sudo yum install -y perl-JSON sudo yum install -y python3-pip sudo pip3


This is hard to read as a merged paragraph. Seems this should be a '::' code literal with line breaks.

dbutenhof · 2020-09-03T17:58:08Z

docs/CONTRIBUTING.rst

+This project uses the flake8 method of code style enforcement, linting
+and checking, `flake8 <http://flake8.pycqa.org/en/latest>`__


Actually a combination of black and flake8, with black set to detect if any files would be modified by the black code formatting rules, and flake8 to check for other Python style errors.

dbutenhof · 2020-09-03T18:00:44Z

docs/CONTRIBUTING.rst

+tox -e agent (for pbench agent) tox -e server (for pbench server) tox -e
+pytest\_agent (for pytest pbench agent) tox -e pytest\_server (for
+pytest pbench server)


Also a "::" code block? Although with the parenthetical descriptions it's not actually code, the merged paragraph is still difficult to follow.

dbutenhof · 2020-09-03T18:04:13Z

docs/GETTING_STARTED.rst

+    sar tool is now registered in group default
+    [debug]tool_opts: default --interval="3"
+    [debug]checking to see if tool is installed...
+    iostat is installed
+    iostat tool is now registered in group default
+    [debug]tool_opts: default --interval="3"
+    [debug]checking to see if tool is installed...
+    mpstat is installed
+    mpstat tool is now registered in group default
+    [debug]tool_opts: default --interval="3"
+    [debug]checking to see if tool is installed...
+    pidstat is installed
+    pidstat tool is now registered in group default
+    [debug]tool_opts: default --interval="3"
+    [debug]checking to see if tool is installed...
+    proc-vmstat tool is now registered in group default
+    [debug]tool_opts: default --interval="3"
+    [debug]checking to see if tool is installed...
+    proc-interrupts tool is now registered in group default
+    [debug]tool_opts: default --record-opts="record -a --freq=100"
+    [debug]checking to see if tool is installed...
+    perf tool is now registered in group default


When I do this I don't get any of the [debug] lines, and I wouldn't expect to see them under normal circumstances. Is this right?

dbutenhof · 2020-09-03T18:04:51Z

docs/GETTING_STARTED.rst

+
+::
+
+    # list-tools


That should be pbench-list-tools

dbutenhof · 2020-09-03T18:05:09Z

docs/GETTING_STARTED.rst

+
+::
+
+    # list-tools --with-options


Again, pbench-list-tools

dbutenhof · 2020-09-03T18:06:20Z

docs/GETTING_STARTED.rst

+
+::
+
+    # register-tool --name=pidstat -- --interval=10


pbench-register-tool

Also, again, I don't think the [debug] log lines in the output are correct.

dbutenhof · 2020-09-03T18:08:45Z

docs/GETTING_STARTED.rst

+If this is the first time running ``fio`` via the ``pbench-agent``,
+``pbench-agent`` will attempt to download and compile ``fio``. You may
+see quite a bit of output from this. Once ``fio`` is installed,
+``pbench-agent`` will run several tests by default. Output for each will
+look something like this:


I guess a question for Pete or Nick, but my understanding is that pbench wasn't doing this anymore; and for me this just gives me an error that fio-3.19 is not installed.

dbutenhof · 2020-09-03T18:20:59Z

docs/pbench-agent.rst

+   register-tool-set
+   user-benchmark -C test1 -- ./your_cmd.sh
+   move-results


All of these are pbench- prefixed commands.

dbutenhof · 2020-09-03T18:22:41Z

docs/pbench-agent.rst

+
+::
+
+   pbench_fio


pbench-fio, not underscore.

portante

Good start.

This adds a new directory, docs. What are you thinking we should do with the existing doc directory? I was hoping we could make these changes in the doc directory, just moving all of the current "mark down" files we have (.md) to reStructuredText that is supported by GitHub.

Does GitHub's rendering of the new documents work as expected?

portante · 2020-09-28T17:57:18Z

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF


Let's remove this file from the commit, we won't be supporting a build on Windows in the foreseeable future.

ndokos

It seems that this is based on a very old set of docs that does not follow current conventions. It needs a fair amount of alterations (the lack of the pbench- prefix on most commands is the most obvious omission).

ndokos · 2020-10-27T21:10:51Z

docs/conf.py

+# -- Project information -----------------------------------------------------
+
+project = 'pbench-docs'
+copyright = '2020, Haowei'


Shouldn't the copyright be assigned to a RH entity?

ndokos · 2020-10-27T21:13:14Z

docs/pbench-agent.rst

+
+::
+
+   move-results


pbench- prefix missing

ndokos · 2020-10-27T21:13:26Z

docs/pbench-agent.rst

+
+::
+
+   copy-results


pbench- prefix missing

ndokos · 2020-10-27T21:14:02Z

docs/pbench-agent.rst

+
+   register-tool-set
+   user-benchmark --config=foo -- myscript.sh
+   move-results


pbench- prefix missing on last three lines

ndokos · 2020-10-27T21:22:47Z

docs/pbench-agent.rst

+   results_repo_dir=/pbench/public_html/incoming
+   ssh_opts='-o StrictHostKeyChecking=no'
+
+These are now specified in the config file


This whole section does not sound right: base does set a bunch of variables but most of these are not specified in the config file. In particular, date, hostname, results_repo and results_repo_dir are not specified in the config file. The last two I can't find anywhere, either in the config file or in base.

ndokos · 2020-10-27T21:23:24Z

docs/pbench-agent.rst

+   ssh_opts='-o StrictHostKeyChecking=no'
+
+These are now specified in the config file
+``/opt/pbench-agent/config/pbench.conf``.


The config file is /opt/pbench-agent/config/pbench-agent.cfg.

ndokos · 2020-10-27T21:23:39Z

docs/pbench-agent.rst

+===============
+
+The configured default set of tools (what you would get by running
+``register-tool-set``) is:


ndokos · 2020-10-27T21:35:27Z

What is the process of publishing these documents on readTheDocs?

pravins · 2023-07-10T05:04:06Z

This has been fixed with #3428
Feel free to reopen if something is missing.

haoweiqiu added 2 commits July 22, 2020 21:43

convert current docs to sphinx and deploy on readthedocs

7fff5d7

modify docs

76bbeec

portante added this to the v0.70 milestone Jul 29, 2020

portante added Agent Documentation enhancement labels Jul 29, 2020

portante self-assigned this Jul 29, 2020

portante requested review from portante and ndokos July 29, 2020 21:19

portante modified the milestones: v0.70, v0.71 Aug 15, 2020

dbutenhof reviewed Sep 3, 2020

View reviewed changes

portante requested changes Sep 28, 2020

View reviewed changes

ndokos requested changes Oct 27, 2020

View reviewed changes

portante changed the base branch from master to main January 28, 2021 22:11

portante removed this from the v0.71 milestone Apr 13, 2021

portante added this to the v0.72 milestone Apr 13, 2021

portante modified the milestones: v0.72, v0.73 Sep 14, 2022

pravins closed this Jul 10, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Convert current pbench MarkDown content to readthedocs and reStructuredText format #1730

Docs: Convert current pbench MarkDown content to readthedocs and reStructuredText format #1730

haoweiqiu commented Jul 23, 2020 •

edited

Loading

portante commented Jul 27, 2020

portante commented Jul 27, 2020

haoweiqiu commented Jul 28, 2020

dbutenhof left a comment

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

dbutenhof Sep 3, 2020

portante left a comment

portante Sep 28, 2020

ndokos left a comment

ndokos Oct 27, 2020

ndokos Oct 27, 2020

ndokos Oct 27, 2020

ndokos Oct 27, 2020

ndokos Oct 27, 2020

ndokos Oct 27, 2020

ndokos Oct 27, 2020

ndokos commented Oct 27, 2020

pravins commented Jul 10, 2023

		This project uses the flake8 method of code style enforcement, linting
		and checking, `flake8 <http://flake8.pycqa.org/en/latest>`__

Docs: Convert current pbench MarkDown content to readthedocs and reStructuredText format #1730

Docs: Convert current pbench MarkDown content to readthedocs and reStructuredText format #1730

Conversation

haoweiqiu commented Jul 23, 2020 • edited Loading

portante commented Jul 27, 2020

portante commented Jul 27, 2020

haoweiqiu commented Jul 28, 2020

dbutenhof left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

portante left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ndokos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ndokos commented Oct 27, 2020

pravins commented Jul 10, 2023

haoweiqiu commented Jul 23, 2020 •

edited

Loading