The plan is to remake the document generator that once worked and create automatic generator of documentation for Discourse.
The output should contain all entities and their fields and data like:
Caption
Name
AllowNulls
DataType
DataLength
Lookups
Description
This documentation could be updated automatically every time a new version is published.
What is expected to be in Lookups and Description?
What about virtual entities and views? Should the be included as well?
What does it mean documentation for Discourse? What is the expected form of output?
How is the automatic update envisioned? What is considered as a new version?
List of lookups created on entity separated by comma that contain the ListDisplayMember field plus filter separated by colon, for example:
Name: GetId, Name: GetOrder
There could be 2 different contents of this field:
Should include all important properties like for example:
Examples:
a, DefaultValue : 100
b, Primary key
c, FK : Priority / Name
For any database field I would like to add a description filed to properties, where the modeller can note anything important to him or her, e.g.:
Shift : Distance from the left corner to the front part (field : description)
Generated and custom description together may look like this for example:
a, DefaultValue : 100, If not specified the value is set up to 100
b, FK: Priority / Name, Name of the priority ordered by ID descending
Yes, lets include them. We can either add another column named “Virtual / View” or add it to description (2.1).
There are more options, one of them is that there will be a page in the client application accessible under a particular user role that will show the documentation online based on the data in the database.
In a more sophisticated form, it would be possible to store the documentation in different time-stamped versions and thus keep track of the progress of development.
We can discuss the topic of effort and benefit here.
There may be just a link to the client app or an information about where the documentation is located and how to access it. This may be more simple than making a generator directly for Discourse. We can discuss this as well.
Here is draft of the final solution.
In addition to Settings, another section - “Documentation” - is added to the standard user menu in the client application.
The page “View Data Items” contains a read-only mirror of the model with the following content:
This will vary and be displayed in separate tables for all different field types:
Functional Fields cannot be displayed in table (we can either find a different way or skip it).
In addition to that is also contains user editable documentation fields:
Editing of these fields interferes with the model because the fields are part of the model, so @washi is against it. However, we currently don’t have another front-end where users can edit these fields, so despite the objections, I suggest using this solution.
Example (with some missing documentation columns):
The users with rights to view this section can see this documentation and export it to Excel as well as part of the standard functionality.
@tvavrda - what is your opinion?
Details to initial implementation:
We might add also general API documentation with the following data:
And others from all API types (on top of Workflow page).
