Cnc25D Internals — Cnc25D 0.1.3 documentation

# Cnc25D 0.1.3 documentation

## Cnc25D Internals

## 1. File layout

    Cnc25D/
      .gitignore
      CHANGES.rst         # Release change notes. Required by PyPI
      LICENSE.txt         # Applicable license
      MANIFEST            # automatically generated by the Python package distribution setup tools
      MANIFEST.in         # include addition files to the Python package distribution
      README.rst          # README used by GitHUb and PyPI
      setup.py            # Python package distribution setup file
      bin/                                    # contains binaries to be installed on the host system during the Cnc25D package installation
        cnc25d_example_generator_src.py       # source code of the cnc25d_example_generator.py script
        cnc25d_example_generator.py           # generated by scr/micropreprocessor.py
      cnc25d/                             # the main package
        __init__.py
        importing_freecad.py              # lets import the FreeCAD libraries
        cnc_cut_outline.py                # cnc25d API to design parts
        export_2d.py                      # cnc25d API to export DXF or SVG
        box_wood_frame.py                 # box_wood_frame design example
        tests/                       # contains the test files of the cnc25d package
          __init__.py
          importing_cnc25d.py        # modify sys.path to import the cnc25d library
          cnc25d_api_macro.py        # usage example of the cnc25d API. Reused by cnc25d_example_generator.py. Can not be executed directly.
          cnc25d_api_test.py         # executable wrapper of cnc25d_api_macro.py
          box_wood_frame_macro.py    # usage example of box_wood_frame. Reused by cnc25d_example_generator.py. Can not be executed directly.
          box_wood_frame_test.py     # executable wrapper of box_wood_frame_macro.py
      docs/                               # cnc25d package documentation sources
        box_wood_frame.svg                # SVG draft
        box_wood_frame.txt                # text autmatically extracted from the SVG draft
        cnc25d_api.rst                    # source of the Sphinx generated documentation
        index.rst                         # top file of the Sphinx documentation sources
        conf.py                           # Sphinx configuration
        Makefile                          # make clean html to rebuild the documentation
        images/                           # contains the images used by the Sphinx documentation
          3_axis_cnc.png
      scr/                                          # additional scripts for developers
        micropreprocessor.py                        # lets generate cnc25d_example_generator.py
        note_on_cnc25d_dev.txt                      # notes for developers

## 2. Design example generation

The binary script cnc25d_example_generator.py just writes example scripts. These example scripts are actually the files cnc25d/tests/cnc25d_api_macro.py and cnc25d/tests/box_wood_frame_macro.py. To check these example scripts, you must run their wrapper scripts cnc25d/tests/cnc25d_api_test.py and cnc25d/tests/box_wood_frame_test.py.

Because of the Python package workflow, the example scripts can not be copied after the installation and must be embedded in the binary script cnc25d_example_generator.py before the creation of the Python package distribution. This is the purpose of the script scr/micropreprocessor.py. The file bin/cnc25d_example_generator_src.py contains the skeleton of the script bin/cnc25d_example_generator.py. The following command include the example scripts to generate the final script bin/cnc25d_example_generator.py:

    > scr/micropreprocessor.py bin/cnc25d_example_generator_src.py

The purpose of this workflow is to help the maintenance of the generated example scripts and avoid bugs in their content.

To create a new design example, follow those steps:

- Create the new design example file in the directory Cnc25D/cnc25d/tests/ with a file name such as my_new_design_macro.py

- Create a wrapper script (eg: my_new_design_test.py) in the same directory that imports the cnc25d package to let run the script my_new_design_macro.py

- Add the few lines in the file Cnc25D/bin/cnc25d_example_generator_src.py that includes the new script Cnc25D/cnc25d/tests/my_new_design_macro.py

- Regenerate Cnc25D/bin/cnc25d_example_generator.py with the command:

      > scr/micropreprocessor.py bin/cnc25d_example_generator_src.py

## 3. Python package distribution release

## 4. Documentation process

SVG files are edited with Inkscape and are use as draft documents for pictures and texts. If you want to modify one of the PNG of the documentation, you can find the vectorial source in one of the SVG files. After modifying the SVG, save it and export the picture as PNG in the directory docs/images/.

A good practice is to use a SVG document with a width of 600 pixels. It helps creating not too large pictures for a nice fitting in html and pdf documents. Extend the height of the SVG document as much as you need it.

Texts can be extracted from the SVG files with the command:

    > scr/svg2txt.py docs/*.svg

The generated txt files are used for checking spelling and are raw material for the reStructuredText files.

The sources of the Sphinx documentation are only the reStructuredText files (*.rst) and the PNG files (*.png).

## 5. Design example recommendations