Skip to contentSkip to conversation

Docs: Convert tbwiki pages into .rst files

PATCH In review Pooja 2 participants 4 messages Nov 25, 2020 – Dec 3, 2020

lore
Share & tools
lore

Pooja

author
#0 lore raw

PATCH 1/1 Docs: Convert tbwiki pages into .rst files

From: Pooja More <[email protected]>

Following pages are converted:
Coding_style.rst
Fuego_directories.rst
Glossary.rst

---
 docs/rst_src/Coding_style.rst      | 111 +++++++++++++++
 docs/rst_src/Fuego_directories.rst | 161 +++++++++++++++++++++
 docs/rst_src/Glossary.rst          | 277 +++++++++++++++++++++++++++++++++++++
 3 files changed, 549 insertions(+)
 create mode 100644 docs/rst_src/Coding_style.rst
 create mode 100644 docs/rst_src/Fuego_directories.rst
 create mode 100644 docs/rst_src/Glossary.rst
docs/rst_src/Coding_style.rst new file +111 -0
new file mode 100644
index 0000000..a190b13
@@ -0,0 +1,111 @@
+###############
+Coding Style
+###############
+
+This page described the coding style conventions used in Fuego.
+
+Please adhere to these conventions, so that the code has a more
+uniform style and it is easier to maintain.  Not all code in Fuego
+adheres to these styles. As we work on code, we will convert it to the
+preferred style over time. New code should adhere to the preferred
+style.
+
+Fuego code consists mostly of shell script and python code.
+
+===============================
+Indentation and line length
+===============================
+
+We prefer indentation to be 4 spaces, with no tabs.
+
+It is preferred to keep lines within 80 columns.  However, this is not
+strict.  If a string constant causes a line to run over 80 columns,
+that is OK.
+
+Some command sequences passed to the 'report' function may be quite
+long and require that they be expressed on a single line.  In that
+case, you can break them up onto multiple lines using shell
+continuation lines.
+
+=======================
+Trailing whitespace
+=======================
+
+Lines should not end in trailing whitespace.  That is: 'grep " $" *'
+should always be empty.
+
+You can do this with: 'grep -R " $" *' in the directory you're working
+in, and fix the lines manually.
+
+Or, another method, if you're using vim, is to add an autocmd to your
+.vimrc to automatically remove whitespace from lines that you edit.
+
+This line in your ~/.vimrc:
+
+::
+
+  autocmd FileType sh,c,python autocmd BufWritePre <buffer> %s/\s\+$//e
+
+
+automatically removes whitespace from all line endings in shell, C,
+and python files that are saved from vim.
+
+Or, a third method of dealing with this automatically is to have git
+check for whitespace errors using a configuration option, or a hook.
+See
+
+`<https://stackoverflow.com/questions/591923/make-git-automatically-remove-trailing-whitespace-before-committing#592014>`_
+
+
+Also, script files should not end in blank lines.
+
+=================
+Shell features
+=================
+
+Shell scripts which run on the device-under-test (DUT or board),
+SHOULD restrict themselves to POSIX shell features only.  Do not
+assume you have any shell features on the target board outside of
+those supported by 'busybox ash'.
+
+Try running 'checkbashisms' on your target-side code, to check for any
+non-POSIX constructs in the code.
+
+The code in ``fuego_test.sh`` is guaranteed to run in bash, and may
+contain bashisms, if needed.  If equivalent functionality is available
+using POSIX features, please use those instead. Please avoid esoteric
+or little-known bash features. (Or, if you use such features, please
+comment them.)
+
+Another useful tool for checking your shell code is 'ShellCheck'.  See
+`<https://github.com/koalaman/shellcheck>`_.  Note that most
+distributions have a package for shellcheck.
+
+There are a few conventions for avoiding using too many external
+commands in shell scripts that execute on the DUT. To check for a
+process, use 'ps' and 'grep', but to avoid having grep find itself,
+use a wildcard in the search pattern.  Like so: 'ps | grep [f]oo'
+(rather than 'ps | grep foo | grep -v grep').
+
+
+================
+Python style
+================
+
+Python code (such as parser code, the overlay generator, ftc and other
+helper scripts), should be compliant with
+`<https://www.python.org/dev/peps/pep-0008/>`_.  As with shell code,
+there is a lot of legacy code in Fuego
+that is not currently compliant with PEP 8.  We will convert legacy
+code to the correct style as changes are made over time.
+
+Here are a few more conventions for Fuego code:
+
+ - Strings consisting of a single character should be declared use single-quotes
+ - Strings consisting of multiple characters should declared using double-quotes,
+   unless the string contains a double-quote.  In that case, single-quotes should
+   be using for quoting, to avoid having to escape the double-quote.
+
+Note that there is a fuego lint test (selftest), called
+Functional.fuego_lint.  It only checks a few files at the moment, but
+the plan is to expand it to check additional code in the future.
docs/rst_src/Fuego_directories.rst new file +161 -0

161 lines not on this page · raw message

docs/rst_src/Glossary.rst new file +277 -0

277 lines not on this page · raw message

Signature · 30 lines
2.7.4


-- 






This
message contains confidential information and is intended only 
for the
individual(s) named. If you are not the intended
recipient, you are 
notified that disclosing, copying, distributing or taking any
action in 
reliance on the contents of this mail and attached file/s is strictly
prohibited. Please notify the
sender immediately and delete this e-mail 
from your system. E-mail transmission
cannot be guaranteed to be secured or 
error-free as information could be
intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain
viruses. The sender therefore does 
not accept liability for any errors or
omissions in the contents of this 
message, which arise as a result of e-mail
transmission.
#1 lore raw

I committed this patch, and updated a lot of content in the Fuego_directories and Glossary files.

I mention one outstanding issue is below...

Quoted 21 lines

-----Original Message-----
From: Pooja <[email protected]>

From: Pooja More <[email protected]>

Following pages are converted:
Coding_style.rst
Fuego_directories.rst
Glossary.rst

---
 docs/rst_src/Coding_style.rst      | 111 +++++++++++++++
 docs/rst_src/Fuego_directories.rst | 161 +++++++++++++++++++++
 docs/rst_src/Glossary.rst          | 277 +++++++++++++++++++++++++++++++++++++
 3 files changed, 549 insertions(+)
 create mode 100644 docs/rst_src/Coding_style.rst
 create mode 100644 docs/rst_src/Fuego_directories.rst
 create mode 100644 docs/rst_src/Glossary.rst
docs/rst_src/Coding_style.rst +0 -0

...

Quoted 26 lines
docs/rst_src/Glossary.rst new file +17 -0
new file mode 100644
index 0000000..61bb3d7
@@ -0,0 +1,277 @@
+##############
+Glossary
+##############
+
+Here is a glossary of terms used in this wiki:
+
+Here is a short table that relates a few Jenkins terms to Fuego terms:
+
+show_sort_link=0
+
+show_edit_links=0
+
+Table:
+
++--------------+------------------+------------------------------------------------------------------------------------------------+
+| Jenkins term |Fuego term        |Description                                                                                     |
++==============+==================+==================================================================================

==============+

+|slave         |''none''          |this is a long-running jenkins process, that executes jobs.  It is usually (?) assigned to a    |
+|              |                  |particular node                                                                                 |
Quoted 14 lines

++--------------+------------------+------------------------------------------------------------------------------------------------+
+|node |board |item being tested (Fuego defines a Jenkins node for each board in the system) |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|job |test |a collection of information needed to perform a single test |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|''none'' |request |a request to run a particular test on a board |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|build |run(or 'test run')|the results from executing the job or test |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|''none'' |plan |the plan has the list of tests and how to run them (which variation, or 'spec' to use) |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+|''none'' |spec |the spec indicates a particular variation of a test |
++--------------+------------------+------------------------------------------------------------------------------------------------+
+

I shortened the lines on this table so that the source is only 80-columns wide.

When rendered by sphinx for html output ('make html'), the resulting html file has a table that is not fit to the page. It has a horizontal scroll bar, instead of expanding the table cells vertically and wrapping the text.

Can you see if there's a setting that would allow this table to appear without needing a scroll bar?

Thanks,
-- Tim

#2 lore raw

Hi,

To avoid scroll bar at bottom of the table:

I made following changes to:

*_static/custom.css:*

.wy-table-responsive table td {
white-space: normal;
}

Declared it in conf.py as:

def setup(app):
app.add_stylesheet('custom.css')

But it did not work. I will update you regarding the same if I find a solution for it.

Thanks and regards

Pooja More

Quoted 105 lines · Tim

I committed this patch, and updated a lot of content in the Fuego_directories and Glossary files.

I mention one outstanding issue is below...

Quoted 10 lines

-----Original Message-----
From: Pooja <[email protected]>

From: Pooja More <[email protected]>

Following pages are converted:
Coding_style.rst
Fuego_directories.rst
Glossary.rst

Quoted 5 lines
---
 docs/rst_src/Coding_style.rst      | 111 +++++++++++++++
 docs/rst_src/Fuego_directories.rst | 161 +++++++++++++++++++++
 docs/rst_src/Glossary.rst          | 277

+++++++++++++++++++++++++++++++++++++

Review

Quoted 6 lines
 3 files changed, 549 insertions(+)
 create mode 100644 docs/rst_src/Coding_style.rst
 create mode 100644 docs/rst_src/Fuego_directories.rst
 create mode 100644 docs/rst_src/Glossary.rst
(quoted diff) +0 -0

b/docs/rst_src/Coding_style.rst
...

Quoted 11 lines
docs/rst_src/Glossary.rst new file +4 -0
new file mode 100644
index 0000000..61bb3d7
@@ -0,0 +1,277 @@
+##############
+Glossary
+##############
+

docs/rst_src/Glossary.rst line 14

Quoted 10 lines
docs/rst_src/Glossary.rst new file +10 -0
+Here is a glossary of terms used in this wiki:
+
+Here is a short table that relates a few Jenkins terms to Fuego terms:
+
+show_sort_link=0
+
+show_edit_links=0
+
+Table:
+

++--------------+------------------+------------------------------------------------------------------------------------------------+

docs/rst_src/Glossary.rst line 15

Quoted 1 line
docs/rst_src/Glossary.rst new file +1 -0
+| Jenkins term |Fuego term        |Description
                                                           |
Quoted 1 line

++==============+==================+==================================================================================

Quoted 2 lines

==============+
+|slave |''none'' |this is a long-running jenkins

process, that executes jobs. It is usually (?) assigned to a |

Quoted 1 line

+| | |particular node

                                                           |
Quoted 1 line

++--------------+------------------+------------------------------------------------------------------------------------------------+

Quoted 1 line

+|node |board |item being tested (Fuego defines a

Jenkins node for each board in the system) |

Quoted 1 line

++--------------+------------------+------------------------------------------------------------------------------------------------+

Quoted 1 line

+|job |test |a collection of information needed

to perform a single test |

Quoted 1 line

++--------------+------------------+------------------------------------------------------------------------------------------------+

Quoted 1 line

+|''none'' |request |a request to run a particular test

on a board |

Quoted 1 line

++--------------+------------------+------------------------------------------------------------------------------------------------+

Quoted 1 line

+|build |run(or 'test run')|the results from executing the job

or test |

Quoted 1 line

++--------------+------------------+------------------------------------------------------------------------------------------------+

Quoted 1 line

+|''none'' |plan |the plan has the list of tests and

how to run them (which variation, or 'spec' to use) |

Quoted 1 line

++--------------+------------------+------------------------------------------------------------------------------------------------+

Quoted 1 line

+|''none'' |spec |the spec indicates a particular

variation of a test |

Quoted 1 line

++--------------+------------------+------------------------------------------------------------------------------------------------+

Quoted 1 line

+

I shortened the lines on this table so that the source is only 80-columns wide.

When rendered by sphinx for html output ('make html'), the resulting html file has a table that is not fit to the page. It has a horizontal scroll bar, instead
of expanding the table cells vertically and wrapping the text.

Can you see if there's a setting that would allow this table to appear without
needing a scroll bar?

Thanks,
-- Tim

Signature · 20 lines
This
message contains confidential information and is intended only 
for the
individual(s) named. If you are not the intended
recipient, you are 
notified that disclosing, copying, distributing or taking any
action in 
reliance on the contents of this mail and attached file/s is strictly
prohibited. Please notify the
sender immediately and delete this e-mail 
from your system. E-mail transmission
cannot be guaranteed to be secured or 
error-free as information could be
intercepted, corrupted, lost, destroyed, 
arrive late or incomplete, or contain
viruses. The sender therefore does 
not accept liability for any errors or
omissions in the contents of this 
message, which arise as a result of e-mail
transmission.
#3 lore raw

Thanks for looking into this.
-- Tim

Quoted 116 lines

-----Original Message-----
From: Pooja Sanjay More <[email protected]>

Hi,

To avoid scroll bar at bottom of the table:

I made following changes to:

_static/custom.css:
.wy-table-responsive table td {
white-space: normal;
}
Declared it in conf.py as:
def setup(app):
app.add_stylesheet('custom.css')
But it did not work. I will update you regarding the same if I find a solution for it. Thanks and regards
Pooja More

On Thu, Dec 3, 2020 at 3:15 AM Bird, Tim <[email protected] <mailto:[email protected]> > wrote:

	I committed this patch, and updated a lot of content in the
	Fuego_directories and Glossary files.

	I mention one outstanding issue is below...

	> -----Original Message-----
	> From: Pooja <[email protected] <mailto:[email protected]> >
	>
	> From: Pooja More <[email protected] <mailto:[email protected]> >
	>
	> Following pages are converted:
	> Coding_style.rst
	> Fuego_directories.rst
	> Glossary.rst
	>
	> Signed-off-by: Pooja More <[email protected] <mailto:[email protected]> >
	> ---
	>  docs/rst_src/Coding_style.rst      | 111 +++++++++++++++
	>  docs/rst_src/Fuego_directories.rst | 161 +++++++++++++++++++++
	>  docs/rst_src/Glossary.rst          | 277 +++++++++++++++++++++++++++++++++++++
	>  3 files changed, 549 insertions(+)
	>  create mode 100644 docs/rst_src/Coding_style.rst
	>  create mode 100644 docs/rst_src/Fuego_directories.rst
	>  create mode 100644 docs/rst_src/Glossary.rst
	>
	> diff --git a/docs/rst_src/Coding_style.rst b/docs/rst_src/Coding_style.rst
	...

	> diff --git a/docs/rst_src/Glossary.rst b/docs/rst_src/Glossary.rst
	> new file mode 100644
	> index 0000000..61bb3d7
	> --- /dev/null
	> +++ b/docs/rst_src/Glossary.rst
	> @@ -0,0 +1,277 @@
	> +##############
	> +Glossary
	> +##############
	> +
	> +Here is a glossary of terms used in this wiki:
	> +
	> +Here is a short table that relates a few Jenkins terms to Fuego terms:
	> +
	> +show_sort_link=0
	> +
	> +show_edit_links=0
	> +
	> +Table:
	> +
	> ++--------------+------------------+------------------------------------------------------------------------------------------------+
	> +| Jenkins term |Fuego term        |Description                                                                                     |
	>

++==============+==================+==================================================================================
> ==============+
> +|slave |''none'' |this is a long-running jenkins process, that executes jobs. It is usually (?) assigned to a |
> +| | |particular node |
> ++--------------+------------------+------------------------------------------------------------------------------------------------+
> +|node |board |item being tested (Fuego defines a Jenkins node for each board in the system) |
> ++--------------+------------------+------------------------------------------------------------------------------------------------+
> +|job |test |a collection of information needed to perform a single test |
> ++--------------+------------------+------------------------------------------------------------------------------------------------+
> +|''none'' |request |a request to run a particular test on a board |
> ++--------------+------------------+------------------------------------------------------------------------------------------------+
> +|build |run(or 'test run')|the results from executing the job or test |
> ++--------------+------------------+------------------------------------------------------------------------------------------------+
> +|''none'' |plan |the plan has the list of tests and how to run them (which variation, or 'spec' to use) |
> ++--------------+------------------+------------------------------------------------------------------------------------------------+
> +|''none'' |spec |the spec indicates a particular variation of a test |
> ++--------------+------------------+------------------------------------------------------------------------------------------------+ > +

I shortened the lines on this table so that the source is only 80-columns wide.

When rendered by sphinx for html output ('make html'), the resulting html file has a table that is not fit to the page. It has a horizontal scroll bar, instead of expanding the table cells vertically and wrapping the text.

Can you see if there's a setting that would allow this table to appear without needing a scroll bar?

Thanks,
-- Tim

This message contains confidential information and is intended only for the individual(s) named. If you are not the intended recipient, you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this mail and attached file/s is strictly prohibited. Please notify the sender immediately and delete this e-mail from your system. E-mail transmission cannot be guaranteed to be secured or error-free as information could be intercepted, corrupted, lost, destroyed, arrive late or incomplete, or contain viruses. The sender therefore does not accept liability for any errors or omissions in the contents of this message, which arise as a result of e-mail transmission.