Skip to Content
  2. Mailing Lists
  3. Contributors
  4. Re: OCA Functional Group - Project Modules Documentation

Archives

Contributors

Re: OCA Functional Group - Project Modules Documentation

Re: OCA Functional Group - Project Modules Documentation

Re: OCA Functional Group - Project Modules Documentation

Hello Yann,

On Mon, Sep 18, 2023 at 4:43 PM Yann Papouin <notifications@odoo-community.org> wrote:
Does the oca-gen-addon-readme tool will fetch these files, copying them into the static folder and re-edit the MD to make relative links ?

That is not planned at this point. It could be interesting, to ensure that all source images are in the repository.

But note that currently, the readme generator currently replaces relative image links by github urls, so the README renders correctly in Odoo and on PyPI.

Best regards,

-Stéphane

by Stéphane Bidoul - 12:37 - 19 Sep 2023

Reference

  • OCA Functional Group - Project Modules Documentation

    After the last OCA Days in 2022, a group of functional people from different countries and companies decided to work together to improve functional contributions in OCA. 


    Documentation of OCA modules has been identified as one of the main areas where functionals’ expertise can be useful. 


    Our primary goals with this project are:

    • to make it easier for everyone to understand what is the purpose of a module and how to use it ;

    • to provide guidelines on how to write good and complete documentation ;

    • to improve access to editing and contribution of module’s documentation for functional people (eg: adding screenshots).


    What are the changes?

    • Implementing Markdown in place of RST for Read Me

      • A great module documentation has screenshots so the reader can understand better how to use the module. The problem is that it is difficult for a functional person to add screenshots into an RST file.  You must upload the image in a folder (and you have to know which one ;) ), then you need to know how to put the link to the image, and if you make a mistake, the image doesn't show…

      • Markdown files are supported by GitHub and this format allows you to insert a screenshot easily by Drag & Drop.

      • Markdown provides a simple and unified layout (as RST do) so we don’t lose this advantage.

      • GitHub provides a Markdown editor tool so you don’t even have to learn the syntax (but, we tell you, it is very easy to learn ;) ) 

    • Providing guidelines for documentation

      • We are still working on the Guidelines but we will have a first version ready for the OCA days!

    • Enhancing Readme template

      • Adding some information into the description of the fragments so anybody (functional or developer) can understand the usage of each fragment.

      • Adding a new CONTEXT fragment. This new fragment can then be used to explain the why (context, use cases) of the module.


    What are the impacts of those changes?

    • The Read Me’s template files have been converted to Markdown.

    • We will be converting, in the next weeks, all Read Me files to Markdown for all repositories in branch “16.0”. 

    • Read Me in RST will still be accepted but we strongly recommend to use Markdown for all the reasons enumerated previously.

    • For the branch “17.0”,  only Markdown files will be accepted.


    How to proceed in case of migration of a module?

    • You can convert existing readme fragments from RST to Markdown for a whole repo using a command such as:

    $ oca-gen-addon-readme --convert-fragments-to-markdown --org-name OCA --repo-name rest-framework --branch 16.0 --addons-dir . --gen-html


    • You can also convert an individual addon with --addon-dir (instead of --addons-dir) with a command like this:

    $ oca-gen-addon-readme --convert-fragments-to-markdown --org-name OCA --repo-name purchase-workflow --branch 16.0 --addon-dir purchase_request --gen-html



    How to proceed in case of pushing a new module into OCA?

    • Using the templates (which are now in Markdown)

    • And we recommend you follow the Guidelines!

      • We will be communicating about these Guidelines when they are ready!


    We hope you enjoy these improvements!!!


    The OCA Functional Group, Documentation Team

    Julie LeBrun, Numigi Solutions

    Francesco Foresti, ooops

    Lara Freeke, Therp

    Benedito Monteiro


    by Julie LeBrun - 04:12 - 18 Sep 2023