We need an App including docstring comments to demonstrate the functionality and for testing purposes.

The needs to be stored in the following formats in the repo: (Zip, mssapp, src folder)

Currently the file path needs to be copied into the fields.

For the fileds:

• Source path
• Output path
• Config file

a file picker needs to be implemented, so the user can select the path/file instead of copy pasting it.

The prefix/suffix differes depending on implementation.

In Azure DevOps ::: is used.
In chrome extension for github ``` is used.

This needs to be reflected via customizable prefix/suffix via config.

The screenflow visualization is currently overloaded, when there are to many navigations from one screen to another e.g. nested in If-statements etc.

• A possible solution could be to filter out multiple (same) navigations an reduce them to one.

Also Back() navigations are currently not tracked at all.

Add possibility to export documentation additionally as pdf. Mermaid diagram an pictures needs to be embedded.

If the app contains a blank screen this results in an error.
AttributeError: 'str' object has no attribute 'items'"
documentation.py line 72

Each of the screen names in the image have 2 or 3 words as the screen name separated by a space.

If I have an element with a Set function which is commented aside the script runs into an error.
OnSelect = Back() //Set(varNav;true)
This is hardly avoidable if you are working with a German Browser.

Since a proper documentation should contain more information that can't be extracted from the source code, this needs to be provided separately.
This could be achieved by providing this content on separated MD files that will be pulled into the documentation file.

Designing the convention. This will be part of the documentation.

Docstring and commenting convention

Documentation strings are placed at the beginning of a property enclosed in /* */

Following the good practice for docstrings in Python https://www.python.org/dev/peps/pep-0257/#id17

they can be either single line docstrings :

/* This is a single line docstring. */

or multi line docstrings:

/* This is a multi line docstring

A detailed explenation can follow here and
take up as many lines as needed
*/

Code comments can occur everywhere in between beginning with // followed by blank

// This is a code comment

Documentation on App level

App related documentation is placed at the beginning of the App.OnStart property (later also App.StartApp)
on app level.

Example:

/* This application enables endusers to book their working hours effectivly.

With this app the endusers can manage their working hours according our internal
policy. …

Foo bar…
*/

Global variables created with Set(varName, function) need to be reflected inside of the documentation.

Dear,

I am adding the Python script to the Azure DevOps pipeline. I cannot install the YAML module; see the message.
ModuleNotFoundError: No module named 'yaml'

Thanks for the feedback.

Frederik

As the StartScreen app variable is now available it should be documented.

In the attached documentation.py I have added the following;

start_screen = app_screen[1]["App As appinfo"].get("StartScreen")

at line 172 and the following in the # write app info block

  if start_screen != None:
            appinfo = self._extract_parts_from_propperty(start_screen)
            if appinfo[1] != None:
                self.md_file.new_paragraph(appinfo[1])
            self.md_file.new_line("")
            self.md_file.new_header(level=2, title="StartScreen")
            self.md_file.insert_code(appinfo[2],language='typescript')
            self.md_file.new_line("")

This also has some updates to Mermaid to work OOTB with Docusaurus, namely ==> becomes --> and screen names cannot have spaces, well I haven't worked out how to yet. Working on Datasources and Tests next :)

documentation - Copy.txt

Currently three ways could be possible:

1. store files in your repository under /docs/media and create a markdown link to the file within the docstring

2. (not recommend but possible) upload files into the app and link to the file in docstring with a relative path to ./Assets/Images

3. create an markdown link within the docstring to an online resource

We reviewed it and noted that the sample files that it does process successfully are different than the ones PA currently generates. Or are we doing something wrong?

An issue in the pipeline step in Azure DevOps:
Config:

YAML Config of the above configuration:

#Your build pipeline references an undefined variable named ‘BuildStagingDirectory’. Create or edit the build pipeline for this YAML file, define the variable on the Variables tab. See https://go.microsoft.com/fwlink/?linkid=865972
#Your build pipeline references an undefined variable named ‘SolutionName’. Create or edit the build pipeline for this YAML file, define the variable on the Variables tab. See https://go.microsoft.com/fwlink/?linkid=865972
#Your build pipeline references an undefined variable named ‘BuildStagingDirectory’. Create or edit the build pipeline for this YAML file, define the variable on the Variables tab. See https://go.microsoft.com/fwlink/?linkid=865972
#Your build pipeline references an undefined variable named ‘SolutionName’. Create or edit the build pipeline for this YAML file, define the variable on the Variables tab. See https://go.microsoft.com/fwlink/?linkid=865972

steps:

• task: PythonScript@0
  displayName: 'powerapps-docstring'
  inputs:
  scriptPath: 'powerapps-docstring/main.py'
  arguments: '--source $(BuildStagingDirectory)$(SolutionName)\managed\ --output $(BuildStagingDirectory)$(SolutionName)\managed\ --config powerapps-docstring\config.yaml'
  continueOnError: true

OUTPUT:

2021-11-07T16:05:32.8040424Z ##[section]Starting: powerapps-docstring
2021-11-07T16:05:32.8327632Z ==============================================================================
2021-11-07T16:05:32.8327960Z Task : Python script
2021-11-07T16:05:32.8328195Z Description : Run a Python file or inline script
2021-11-07T16:05:32.8328433Z Version : 0.182.0
2021-11-07T16:05:32.8328748Z Author : Microsoft Corporation
2021-11-07T16:05:32.8329065Z Help : https://docs.microsoft.com/azure/devops/pipelines/tasks/utility/python-script
2021-11-07T16:05:32.8329462Z ==============================================================================
2021-11-07T16:05:33.1525497Z [command]C:\hostedtoolcache\windows\Python\3.9.7\x64\python.exe D:\a\1\s\powerapps-docstring\main.py --source build\SolutionDemo\managed\ --output build\SolutionDemo\managed\ --config config.yaml
2021-11-07T16:05:33.2411939Z build\SolutionDemo\managed/
2021-11-07T16:05:33.2412839Z Traceback (most recent call last):
2021-11-07T16:05:33.2413325Z File "D:\a\1\s\powerapps-docstring\main.py", line 86, in
2021-11-07T16:05:33.2413942Z main(sys.argv[1:])
2021-11-07T16:05:33.2414362Z File "D:\a\1\s\powerapps-docstring\main.py", line 79, in main
2021-11-07T16:05:33.2414816Z docstring = Docstring(pa_src_path, output_path, config)
2021-11-07T16:05:33.2415299Z File "D:\a\1\s\powerapps-docstring\powerapps_docstring\documentation.py", line 15, in init
2021-11-07T16:05:33.2415796Z self.manifest_file = self.parser.get_canvas_manifest()
2021-11-07T16:05:33.2416293Z File "D:\a\1\s\powerapps-docstring\powerapps_docstring\parser.py", line 44, in get_canvas_manifest
2021-11-07T16:05:33.2416744Z return canvas_manifest
2021-11-07T16:05:33.2417163Z UnboundLocalError: local variable 'canvas_manifest' referenced before assignment
2021-11-07T16:05:33.2524300Z ##[error]The process 'C:\hostedtoolcache\windows\Python\3.9.7\x64\python.exe' failed with exit code 1
2021-11-07T16:05:33.2731262Z ##[section]Finishing: powerapps-docstring

Since the current setup requires the user to either:
a) have a pipeline running for power apps (rare in the wild) or
b) have python installed and basic knowledge of cli
both ways are difficult for low-code developers. Therefor we need a way to make the functionality accessible for those targeted groups.

Therefor the following solutions could be feasible.:

• providing a standalone .exe file with gui
• providing a web-app (online service) where the .zip or .msapp file can be uploaded and the documentation is extracted and downloadable for the user

In this issue we collect all feature ideas.
Feel free to comment your idea here.

feature requests

• screenflow from navigations #12
• created screens
• docstrings
• used controlls and propperties (configurable?)
• used connections
• output (user? and technical documentation, markdown, html, pdf)
• handels (zip, mssap, src)
• usable via DevOps CI-CD pipeline

The early alpha should at least include:

• basic programm structure
• basic documentation output
• running on the src folder

This shall be considered as a prof of concept version.

• needs to be checked within a pipeline

The Outputfile follows currently a preset structure. This could be changed to a dynamically created document following a structure based on a config file arranging building blocks.

This can be stored in a list:

blocks: ["connections", "screens"]

Reserved blocks are: connections, screens, flows