10. Cnc25D Internals¶

10.1. File layout¶

Cnc25D/
  .gitignore
  CHANGES.rst         # Release change notes. Required by PyPI
  LICENSE.txt         # Applicable license
  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_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.
      box_wood_frame_macro.py     # usage example of box_wood_frame. Reused by cnc25d_example_generator.py. Can not be executed directly.
  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

10.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. The test-macro script must have those lines at the beginning of the script, so it can be excuted in the source repository as well as in the installed environment:

try:    # when working with an installed Cnc25D package
  from cnc25d import cnc25d_api
except: # when working on the source files
  import importing_cnc25d # give access to the cnc25d package
  from cnc25d import cnc25d_api
cnc25d_api.importing_freecad()

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
Check it by executing it
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
```

_images/design_script_example_generation.png

10.3. Python package distribution release¶

10.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).

Cnc25D 0.1.10 documentation