Doc contribution

On this page, you will find the guidelines to contribute to PYLEECAN documentation. PYLEECAN documentation (aka this website) is generated with sphinx by scanning the code of the project. You can contribute to the doc in two ways: by writing docstring (method and object documentation) or directly some new pages for this website.

Before introducing the doc contribution guidelines, we will present you the docstrings format used in PYLEECAN modules and we will explain how we generate the documentation with Sphinx. The generated documentation is available on its own Github repository pyleecan-doc where we will gladly welcome your doc contribution.

Docstring & Sphinx

PYLEECAN docstring format

For PYLEECAN’s modules documentation, the chosen docstring format is numpydoc which is the most used format by the scientific community to document projects (and supported by sphinx).

The numpydoc docstring guide explains in details how to write docstrings in numpydoc format.

Here an example of docstrings in a PYLEECAN module

def build_geometry(self, sym=1, alpha=0, delta=0):

    """Build the geometry of the machine

    Parameters
    ----------
    self : Machine
        Machine object
    sym : int
        Symmetry factor (1= full machine, 2= half of the machine...)
    alpha : float
        Angle for rotation [rad]
    delta : complex
        Complex value for translation
    is_simplified: bool
        True to avoid line superposition

    Returns
    -------
    surf_list : list
        list of surfaces needed to draw the lamination
    """

You can see the page generated by Sphinx from this docstring here and the code of the method by clicking on [source].

Sphinx

Sphinx is used to generate the PYLEECAN website by parsing the project and generating “.rst” files (reStructuredText) according to the documentation (docstrings: numpydoc) in each module of the project. These “.rst” files will then be used by Sphinx to generate the html pages of this website.

To add pages to PYLEECAN website, one can directly add a “.md” file (Markdown) and regenerate the html pages. You can see the .md file used to generate each page by clicking on show source on the left side bar of each page.

As example, here is the development main page .rst file:

Doc contributing guidelines

There are two different ways to contribute to documentation:

• By adding docstrings in python modules to document a specific segment of code. For example the function square below, with docstrings in the triple quotes.

def square(param1):

    """Return the square of param1

    Parameters
    ----------
    param1 : type of the parameter (int)
            description of the parameter
    Returns
    -------
    res type of the value returned (int)
        description of the value returned
    """
    res =  param1 ** 2
    return res

In this case you then need to commit your modifications and make a pull request to submit your contribution to the pyleecan code repository. Once your modifications merged, we will regenerate the doc and update the website ourselves.

• By adding (or correcting) a .rst file, for instance

  • if you have developed a new feature and you want to make a tutorial, you can add new “.rst” files.

  • if you have found some errors (typos) in the documentation and you want to correct it. In this case you can correct them on pyleecan-doc repository by finding and correcting the corresponding “rst” file. You can do that directly through Github (it will automatically create a fork of the repository in your github account).

Then you should submit your contribution on pyleecan-doc repository to share with the community. After your modifications merged and the html pages regenerated, the submitted documentation will be available on the PYLEECAN website.