[FEATURE] Need "Contributing" documentation for Python scripts

[TimJTi]

Is your feature request related to a problem? Please describe.

I had a problem after submitting a PR with a Python script due to a)my non-existent experience of Python and b) no guidelines on the style (and style checkers) needed for scripts.

Describe the solution you'd like

Having grappled with Python for the first time and submitting a PR with a script...finding it failed CI despited running checkpatch.sh...then finding I needed black, isort and flake8 installed...and then finding I needed to actually format my code using black before running the checks...and breath...

I think some guidelines for Python script contributions might be in order (unless I missed them).

Since I am totally new to Python I don't think I'm best qualified to do this.

Can anyone oblige?

Describe alternatives you've considered

No response

Verification

• [x] I have verified before submitting the report.

[fdcavalcanti]

You are right, we are missing documentation regarding Python linting. We do however have instructions on using pre-commit, it should automatically run the Python linting tools: link.

[TimJTi]

You are right, we are missing documentation regarding Python linting. We do however have instructions on using pre-commit, it should automatically run the Python linting tools: link.

Ok - interesting! Didn't know about that tool, but would still be useful to have guidance on just how NuttX wants python scripts to be formatted, before you even write one, I think? But maybe anyone who actually does Python would by default use black etc.? I was - and still am - a novice with Python lol.

[simbit18]

Hi @TimJTi this PR #16561 (for checkpatch.sh), add checking all necessary tools and installation info (more user-friendly)

[TimJTi]

Thanks! I'm away but will take a look next week.

Would it be possible to add a few lines to the Contributing documentation too?

[simbit18]

Would it be possible to add a few lines to the Contributing documentation too?

@TimJTi unfortunately I don't have much time to work on documentation.

[TimJTi]

Can you find 2 minutes to write a few lines here that, to you, are important things a potential contributor of a python script should do?

I am assuming those 3 weird stylers are a given but anything else?

Maybe we can build up a paragraph or 2 with input from others that I can then turn into the requisite documentation PR: I will always (eventually!) find the time for documentation.

[simbit18]

Hi, @TimJTi I hope this will help

checkpatch.sh is a bash script that make use of nxstyle and codespell tools to format patches and files conform to NuttX coding standard.
For example, it has been used in NuttX github action PR check build

https://nuttx.apache.org/docs/latest/components/tools/index.html#checkpatch-sh


The checkpatch.sh script currently checks these types of files:

*************************************
C code
------------------------------------

File: .h, .c

Tools required: nxstyle 

nxstyle: https://nuttx.apache.org/docs/latest/components/tools/index.html#nxstyle-c

*************************************
Python
------------------------------------

File: .py

Tools required: black isort flake8 -> "pip install black isort flake8"

black: An code formatter that automatically formats your Python code.
isort: A tool for sorting Python imports in a consistent and organized manner.
flake8: A code linting tool that checks your code and identifies potential issues.

Use: black <src>

*************************************
Rust
------------------------------------

File: .rs
Tools required: rustfmt -> "rustup component add rustfmt"

rustfmt: A tool for formatting Rust code according to style guidelines
*************************************
CMake
------------------------------------
File: CMakeLists.txt, .cmake

Tools required: cmake-format -> "pip install cmake-format"

Use: cmake-format <src> -o <dst>
cmake-format: A tool for formatting CMake file.
*************************************

also check out

*************************************
All files
------------------------------------
File: All file

Tools required:
   codespell -> "pip install codespell"
   cvt2utf -> "pip install cvt2utf"

codespell: A tool simple spell checker
           https://pypi.org/project/codespell/
cvt2utf: A tool converts non-UTF-encoded files to UTF-8 encoding
         https://github.com/x1angli/cvt2utf

Checks that files do not have execution permissions. (Only .bat, .sh and .ph allowed).

[TimJTi]

Amazing- much better than I dared hope for! I will turn that into a PR in the next few weeks and hopefully others can add to it 😀

[simbit18]

very schematic but useful !!! :)