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](https://en.wikipedia.org/wiki/Docstring) 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](https://github.com/Eomys/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](https://numpydoc.readthedocs.io/en/latest/format.html) explains in details how to write docstrings in numpydoc format. Here an example of docstrings in a PYLEECAN module ``` {.sourceCode .python} 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](pyleecan.Methods.Machine.Machine.build_geometry.md) and the code of the method by clicking on **[source]**. ### Sphinx [Sphinx](http://www.sphinx-doc.org/en/master/) 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](https://www.markdownguide.org/basic-syntax/)) 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: ![](_static/development.png) 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. ``` {.sourceCode .python} 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](code.contribution.md) to the [pyleecan code](https://github.com/Eomys/pyleecan) 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](https://github.com/Eomys/pyleecan-doc) 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](integrate.contribution.md) on [pyleecan-doc repository](https://github.com/Eomys/pyleecan-doc) to share with the community. After your modifications merged and the html pages regenerated, the submitted documentation will be available on the PYLEECAN website.