Maxx 55788 add samples to how tos

.github/workflows/checks-workflow.yml

@@ -11,5 +11,5 @@ jobs:
         # this is a mega hack, to be fixed
         run: |
             sudo apt-get install pylint3 dos2unix
-            chmod +x ./checks.sh
-            ./checks.sh
+            chmod +x ./scripts/checks.sh
+            ./scripts/checks.sh

.pylintrc

@@ -433,7 +433,7 @@ ignored-classes=optparse.Values,thread._local,_thread._local
 # (useful for modules/projects where namespaces are manipulated during runtime
 # and thus existing member attributes cannot be deduced by static analysis). It
 # supports qualified module names, as well as Unix pattern matching.
-ignored-modules=pymxs,ptvsd,PySide2
+ignored-modules=pymxs,ptvsd,PySide2,menuhook
 
 # Show a hint with possible names when a member name was not found. The aspect
 # of finding the hint is based on edit distance.

README.md

@@ -1,6 +1,6 @@
 # How To - Practical Examples For Python
 
-![Splash](Splash.png)
+![Splash](/doc/Splash.png)
 
 This repo contains various Python programming samples.
 
@@ -15,133 +15,67 @@ practice to package 3ds Max Python tools with pip, we provide all our examples i
 It is not necessary to install the HowTos: the repo can simply be used as a passive
 directory of samples and documentation for Python developers.
 
-This being said, it is also possible to install the samples in 3ds Max. This 
-will add a Python3 scripting menu to 3ds Max:
+- Installing the HowTos will add menu items to 3ds Max, and is documented [here](doc/install.md)
+- After an update from github it is necessary to rerun install scripts to get everything 
+working as expected
 
-![Integration](Integration.png)
-
-The examples and some development goodies will be made available from there.
-
-The installation does the following:
-- it installs pip in your 3ds Max installation if it's not already there
-- it installs pystartup.ms that enables auto start pip packages
-- it installs all the samples in --user and -e mode with pip
-
-If you decide to install the howtos, it is highly recommended that you clone
-this git repository locally using git bash (whenever we update the samples,
-you will be able to update your local version and re-run the installation scripts):
-
-```bash
-# from the directory where you want the sample
-git clone https://github.com/ADN-DevTech/3dsMax-Python-HowTos.git
-```
-
-Also note that *all installation steps decribed here also use git bash* (it is
-possible to use another client for git but all installation scripts in
-this repo use bash).
-
-### Option A: Install Everthing Locally in One Step (--user)
-> Note: the steps described here need to be done from a git bash prompt
-
-The [install.sh](install.sh) script can be used from bash
-to install the samples in 3ds Max. The script needs to be run from a
-3ds Max installation directory.
-
-### Option B: Install Everything Locally in Two Steps (--user)
-> Note: the steps described here need to be done from a git bash prompt
+## Python How Tos
 
-It is possible to break up the installation in two steps.
+The samples below are translations of [MAXScript How Tos](https://help.autodesk.com/view/3DSMAX/2020/ENU/?guid=GUID-25C9AD58-3665-471E-8B4B-54A094C1D5C9) that
+can be found in the 3ds Max online documentation.
 
-- The [installstartup.sh](installstartup.sh) script can be used
-from bash to install pip and [pystartup.ms](/pystartup/pystartup.ms).
-It needs to run in the 3ds Max installation directory.
+The conversion from MaxScript to Python could have been more mechanical but we chose to implement
+the Python version in the best Python way known to us. An example of this is that we use PySide2
+(Qt) for the UI as much as possible instead of using more traditional 3ds Max ui mechanisms.
 
-You may do only this step if you don't want the HowTos but you
-want to install pip and pystartup.ms.
+*How To?*
 
-- The [installhowtos.sh](installhowtos.sh) script can be used from
-bash to pip install all the howtos in `--user` mode and `-e` mode (--user
-means that the samples will be intalled under `~/AppData/Roaming/Python/Python37/site-packages/`,
-and -e means that the packages will be installed as symlinks to the 
-source directories so that if the sources change the packages don't need
-to be reinstalled).
-This script needs to run in the 3ds Max installation directory.
+- Develop a Transform Lock Script [transformlock](/src/packages/transformlock/README.md)
+- Remove all materials [removeallmaterials](/src/packages/removeallmaterials/README.md)
+- Quickly rename selected objects [renameselected](/src/packages/renameselected/README.md)
+- Output Object Data to File [speedsheet](/src/packages/speedsheet/README.md)
+- Create a quick video preview [quickpreview](/src/packages/quickpreview/README.md)
+- Access the Z-Depth Channel [zdepthchannel](/src/packages/zdepthchannel/README.md)
 
-## Uninstalling the HowTos
+## Python Examples that don't come from maxscript howtos
 
-The steps needed to uninstall the HowTos can be found in [uninstall.md](uninstall.md).
+- Update a progressbar from a Python thread [threadprogressbar](/src/packages/threadprogressbar/README.md)
+- Create a single instance modal dialog [singleinstancedlg](/src/packages/singleinstancedlg/README.md)
+- Add menu items to open documentation pages in the web browser [inbrowserhelp](/src/packages/inbrowserhelp/README.md)
 
-### Option C: Install the howtos in a virtual environment
-> Note: the steps described here need to be done from a git bash prompt
+## Python Samples
 
-This last option requires three steps.
+Python samples can be found in [src/samples](/src/samples). These samples may already be in your 3ds Max
+installation directories.
 
-It can be used to install the HowTos in a virtual environment (ex:
-you may want to have a virtual environment for Python development).
+## 3dsMax startup entry point
 
-- The first step is the same as the first step described in option B:
-[installstartup.sh](installstartup.sh) needs to run in the 3ds Max
-installation directory to install pip if it is missing and pystartup.
+[pystartup](/src/pystartup/README.md) provides the maxscript code that, when copied to 3ds Max's
+startup directory, will automatically launch pip packages with the 3dsMax startup
+entry point.
 
-- The second step consists in installing virtualenv with pip and creating a
-virtual environment. These steps are described in the [3ds Max documentation](http://help.autodesk.com/view/MAXDEV/2021/ENU/?guid=__developer_python_3_support_virtual_env_html).
-- The last step consists in installing the HowTos in the virtual environment.
-From the same git bash prompt, the [installhowtos.sh](/installhowtos.sh)
-script can be used to install the HowTos in a virtual environment. First `cd`
-to the directory of the virtual env and then (without activating the env) simply
-run [installhowtos.sh](/installhowtos.sh) from that directory.
+## Tools
 
-## Packages that are not examples but that are provided in this repo
+The following packages are not really examples but python tools.
 
-- [menuhook](menuhook/README.md) is not meant to be an example (but is still interesting as such!) but
+- [menuhook](/src/packages/menuhook/README.md) is not meant to be an example (but is still interesting as such!) but
 as a way of attaching Python functions to 3ds Max menu items. The menuhook package is used by 
 most of the other samples.
 
-- [realoadmod](reloadmod/README.md) is small tool that will reload all development modules in one
+- [realoadmod](/src/packages/reloadmod/README.md) is small tool that will reload all development modules in one
 operation
 
-- [mxvscode](mxvscode/README.md) is a small tool that will automatically import ptvsd (the
+- [mxvscode](/src/packages/mxvscode/README.md) is a small tool that will automatically import ptvsd (the
 VSCode debugging interface) during the startup of 3ds Max and make it accept remote connections.
 This may slow down the startup of 3ds Max quite a bit and is meant as a developer-only tool.
 
-
-## Python How Tos
-
-The samples below are translations of [MAXScript How Tos](https://help.autodesk.com/view/3DSMAX/2020/ENU/?guid=GUID-25C9AD58-3665-471E-8B4B-54A094C1D5C9) that
-can be found in the 3ds Max online documentation.
-
-The conversion from MaxScript to Python could have been more mechanical but we chose to implement
-the Python version in the best Python way known to us. An example of this is that we use PySide2
-(Qt) for the UI as much as possible instead of using more traditional 3ds Max ui mechanisms.
-
-*How To?*
-
-- Develop a Transform Lock Script [transformlock](transformlock/README.md)
-- Remove all materials [removeallmaterials](removeallmaterials/README.md)
-- Quickly rename selected objects [renameselected](renameselected/README.md)
-- Output Object Data to File [speedsheet](speedsheet/README.md)
-- Create a quick video preview [quickpreview](quickpreview/README.md)
-- Access the Z-Depth Channel [zdepthchannel](zdepthchannel/README.md)
-
-## Python Examples that don't come from maxscript howtos
-
-- Update a progressbar from a Python thread [threadprogressbar](threadprogressbar/README.md)
-- Create a single instance modal dialog [singleinstancedlg](singleinstancedlg/README.md)
-- Add menu items to open documentation pages in the web browser [inbrowserhelp](inbrowserhelp/README.md)
-
-## 3dsMax startup entry point
-
-[pystartup](pystartup/README.md) provides the maxscript code that, when copied to 3ds Max's
-startup directory, will automatically launch pip packages with the 3dsMax startup
-entry point.
-
 ## Extra Goodies
 
-- [create.sh](create.sh) will generate an empty pip package in the current working directory.
 - [install.sh](install.sh) will install pip, install pystartup and pip install all the samples
 - [uninstall.sh](uninstall.sh) will uninstall what was installed with install.sh
 - [installstartup.sh](installstartup.sh) will install pip and pystartup and nothing more
 - [installhowtos.sh](installhowtos.sh) will install only the howtos (works in a virtual env)
-- [checks.sh](checks.sh) runs pylint on the code, validates that 3ds Max is named properly,
+- [checks.sh](/scripts/checks.sh) runs pylint on the code, validates that 3ds Max is named properly,
 validates that code blocks in markdown always specify the programming language, checks that
 all links are valid in all markdown files of the repo
+- [create.sh](/scripts/create.sh) will generate an empty pip package in the current working directory.

doc/install.md

@@ -0,0 +1,79 @@
+# Installation
+
+It is possible to install the samples in 3ds Max. This 
+will add a Python3 scripting menu to 3ds Max:
+
+![Integration](/doc/Integration.png)
+
+The examples and some development goodies will be made available from there.
+
+The installation does the following:
+- it installs pip in your 3ds Max installation if it's not already there
+- it installs pystartup.ms that enables auto start pip packages
+- it installs all the samples in --user and -e mode with pip
+
+If you decide to install the howtos, it is highly recommended that you clone
+this git repository locally using git bash (whenever we update the samples,
+you will be able to update your local version and re-run the installation scripts):
+
+```bash
+# from the directory where you want the sample
+git clone https://github.com/ADN-DevTech/3dsMax-Python-HowTos.git
+```
+
+Also note that *all installation steps decribed here also use git bash* (it is
+possible to use another client for git but all installation scripts in
+this repo use bash).
+
+### Option A: Install Everthing Locally in One Step (--user)
+> Note: the steps described here need to be done from a git bash prompt
+
+The [install.sh](/install.sh) script can be used from bash
+to install the samples in 3ds Max. The script needs to be run from a
+3ds Max installation directory.
+
+### Option B: Install Everything Locally in Two Steps (--user)
+> Note: the steps described here need to be done from a git bash prompt
+
+It is possible to break up the installation in two steps.
+
+- The [installstartup.sh](/installstartup.sh) script can be used
+from bash to install pip and [pystartup.ms](/src/pystartup/pystartup.ms).
+It needs to run in the 3ds Max installation directory.
+
+You may do only this step if you don't want the HowTos but you
+want to install pip and pystartup.ms.
+
+- The [installhowtos.sh](/installhowtos.sh) script can be used from
+bash to pip install all the howtos in `--user` mode and `-e` mode (--user
+means that the samples will be intalled under `~/AppData/Roaming/Python/Python37/site-packages/`,
+and -e means that the packages will be installed as symlinks to the 
+source directories so that if the sources change the packages don't need
+to be reinstalled).
+This script needs to run in the 3ds Max installation directory.
+
+## Uninstalling the HowTos
+
+The steps needed to uninstall the HowTos can be found in [uninstall.md](/doc/uninstall.md).
+
+### Option C: Install the howtos in a virtual environment
+> Note: the steps described here need to be done from a git bash prompt
+
+This last option requires three steps.
+
+It can be used to install the HowTos in a virtual environment (ex:
+you may want to have a virtual environment for Python development).
+
+- The first step is the same as the first step described in option B:
+[installstartup.sh](/installstartup.sh) needs to run in the 3ds Max
+installation directory to install pip if it is missing and pystartup.
+
+- The second step consists in installing virtualenv with pip and creating a
+virtual environment. These steps are described in the [3ds Max documentation](http://help.autodesk.com/view/MAXDEV/2021/ENU/?guid=__developer_python_3_support_virtual_env_html).
+- The last step consists in installing the HowTos in the virtual environment.
+From the same git bash prompt, the [installhowtos.sh](/installhowtos.sh)
+script can be used to install the HowTos in a virtual environment. First `cd`
+to the directory of the virtual env and then (without activating the env) simply
+run [installhowtos.sh](/installhowtos.sh) from that directory.
+
+

uninstall.md → doc/uninstall.md

@@ -55,7 +55,7 @@ The HowTos can be uninstalled individually by calling:
 
 ## Uninstalling all the HowTos at Once (manual uinstall)
 
-The [uninstallhowtos.sh](uninstallhowtos.sh) can be used
+The [uninstallhowtos.sh](/uninstallhowtos.sh) can be used
 to uninstall all the howtos at once. This will automatically call
 `./python.exe -m pip uninstall` for all the HowTos packages.
 

install.sh

@@ -1,7 +1,7 @@
 #! /usr/bin/env bash
 set -e
 script=$(dirname $(readlink -f "$0"))
-source "$script/inst.sh" 
+source "$script/scripts/inst.sh" 
 
 # make sure we have 3ds Max in the current path
 if [ ! -f ./3dsmax.exe ] 

installhowtos.sh

@@ -1,7 +1,7 @@
 #! /usr/bin/env bash
 set -e
 script=$(dirname $(readlink -f "$0"))
-source "$script/inst.sh"
+source "$script/scripts/inst.sh"
 
 # make sure cygpath is available
 if ! command -v cygpath >/dev/null 2>&1
@@ -18,7 +18,7 @@ fi
 venvscript () {
     echo "cd Scripts"
     echo "call activate.bat"
-    for f in $(find "$script" -name "setup.py")
+    for f in $(find "$packagedir" -name "setup.py")
     do
         local package=$(dirname "$f")
         echo "pip.exe install -e \"$(cygpath -d "$package")\""

installstartup.sh

@@ -1,7 +1,7 @@
 #! /usr/bin/env bash
 set -e
 script=$(dirname $(readlink -f "$0"))
-source "$script/inst.sh" 
+source "$script/scripts/inst.sh" 
 
 # make sure we have 3ds Max in the current path
 if [ ! -f ./3dsmax.exe ] 

checks.sh → scripts/checks.sh

@@ -1,24 +1,35 @@
 #! /usr/bin/env bash
 set -e
 script=$(dirname $(readlink -f "$0"))
+packagedir="$script/../src/packages" 
 workdir=$(pwd)
 IFS=$'\n'
+pl=pylint3
 
+lintdir() {
+    comment="$1"
+    folder="$2"
+    echo "$comment"
+    $pl "$folder"
+    # also prevent runtime.execute
+    if grep -n -R -E "runtime\.execute\(|rt.execute\(" --include '*.py' "$folder"
+    then 
+        echo "pymxs.execute used"
+        exit 1
+    fi
+}
 lint() {
-    for f in $(find . -name "setup.py")
+    for f in $(find "$packagedir" -name "setup.py")
     do
         local package=$(basename $(dirname "$f"))
-        echo "$package" 
-        pylint3 "./$package/$package"
-        # also prevent runtime.execute
-        if grep -n -R -E "runtime\.execute\(|rt.execute\(" --include '*.py' "./$package/$package"
-        then 
-            echo "pymxs.execute used"
-            exit 1
-        fi
+        lintdir "$package" "$packagedir/$package/$package"
     done
 }
 
+lintsamples() {
+    lintdir "samples" "$script/../src/samples"
+}
+
 checkmarkdown() {
     # find code blocks in markdown that don't specify the language
     git grep -n '```' -- "*.md" | 
@@ -50,12 +61,12 @@ checkmdlinks() {
             fi
         elif [[ "$url" =~ ^/.* ]]
         then
-            if [ ! -f "$workdir$url" ]
+            if [ ! -e "$workdir$url" ]
             then
                 echo "$file$line: Broken absolute link: $url"
             fi
         else
-            if [ ! -f "$filedir/$url" ]
+            if [ ! -e "$filedir/$url" ]
             then
                 echo "$file:$line: Broken relative link: $url"
             fi
@@ -73,5 +84,6 @@ checkmarkdownlinks() {
 
 
 lint
+lintsamples
 checkmarkdown
 checkmarkdownlinks