HANA project : Generate project documentation (init)

[yannmiquel]

Hi everyone,

I would like to share with you a project I’m starting. The aim of this project is to generate easily a documentation for HANA database module.

Motivation

One of the projects I was working on has a lot of calculated columns in its calculation views.  Therefore I needed to deliver a proper documentation about these. The SAP IDE (WebIDE or BAS) provides a documentation generated for the calculation view but it only displays the expression of the calculated fields if they are defined in the last node. Moreover, it’s a manual operation (one must manually generate it for each CV) and the output is a html file, which is cumbersome to adapt for a corporate template.

The project

The final goal is to have a proper documentation for the whole project, based on the source code of the HANA database module. But let's start small, with a proper documentation for all of the calculated columns in the project.

So, I wrote a piece of code (in native python) which read all of the files *.hdbcalculationview in a directory, extract the calculation columns (expression, datatype, label, node of definition) and generate a markdown.

It generates a markdown with the following structure:

• Subsection (h2): the name of the calculation view
  
  
  
  • Subsubsection (h3): the label of the calculated column
    
    
    
    • list of the name of the column, datatype, and where it is created
    
    
    • Replication of the formula
    
    
    
    
  
  
  
  

Example:

The markdown format is really nice because it can be read online in GitLab/GitHub and it can easily be converted into  Word or PDF matching a corporate template (using pandoc for example).

How to use it ?

After cloning the repo, open a command prompt and execute this statement:

python make_doc.py "path of the HDB module"

The markdown file will be generated at the root of this path.

The language (EN/FR) is hard coded in the .py file but it will be soon in the args of the cmd statement.

Later, I plan to make it easier to use in a GitHub/GitLab pipeline, so one can be sure that the documentation reflects the source code of the project after any commit.

What's next ?

At this stage, the documentation is incomplete but I’m confident that one can soon have a complete document if some others are involved in this project. That’s why I’m sharing with you my repo autodoc-hdb-module. Feel free to submit any pull requests to enhance the functionalities. I've listed some next steps but one can discuss it.

Conclusion

One can see here another possibility to extract information from the source code of a SAP HANA project in a flexible format. If you share interest in this project, please like this post so I can have an idea of the popularity of this topic. If you're using another tool to generate the documentation, please tell it in the comment section. The documentation of the HANA projects is not a common subject, so it would be really interesting that we share our experience in the comments.

Don't forget to follow the SAP HANA environment Topic page, post and answer questions, and read other posts on the topic.

Have a nice day

Yann