search

openmobilityfoundation / mobility-data-specification

A data standard to enable right-of-way regulation and two-way communication between mobility companies and local governments.
https://www.openmobilityfoundation.org/about-mds/
Other
683 stars 231 forks source link

Autogenerate image documentation #375

Closed hunterowens closed 1 year ago

hunterowens commented 4 years ago

Describe the bug The agency state machine diagram often goes out of sync with the actual state machine. Let's have this diagram be auto generated by a script and inherit from the JSON schema. @karcass volunteered to tackle this.

To Reproduce Steps to reproduce the behavior:

Expected behavior Update the releaseProcess doc to make sure we regenerate the image.

Additional context Add any other context about the problem here.

HenriJ commented 4 years ago

@karcass are you still volunteering to do that ? (I see @hunterowens unassigned you a couple of days later) ? If not, how did you generate the image ?

@hunterowens Are you sure we have enough information inside the JSON schema to generate the transition diagram ?

marie-x commented 4 years ago

Yes, I have someone working on the generator app. ETA uncertain but it'll definitely be done for 0.4.1.

Retzoh commented 4 years ago

@sarob as discussed in the city-services meeting, this issue should be moved to the 0.5.0 milestone.

Retzoh commented 4 years ago

We are waiting for #271 to be solved.

schnuerle commented 4 years ago

271 is now solved. And we have a new State Machine Diagram. Right now it's being managed in Slides and is pretty easy to edit and save as an SVG to the repo.

@thekaveman made an auto generator, but the results were not as clear or intuitive. I think we should keep this manual process in place for now since the diagram doesn't change much and readability is more important that autogeneration.

schnuerle commented 4 years ago

@janedotx autogenerated an image, and it was also very complex and not easy to read. I like the idea of autogenerating not only this, but the schemas as well. But given the current complexity of the vehicle state events and the state machine diagram, I can't think of a good way to autogenerate the diagram and have it readable, presentable as an image, editable at no cost, and visually appealing.

If anyone wants to tackle this still, and has ideas on a solution, please leave a comment here.

schnuerle commented 1 year ago

Have you all seen how complex these state machines are!? I don't think they could be auto generated easily from the table. I'm giving up the dream and closing this down...

schnuerle commented 2 months ago

I know this is closed, but adding that GitHub now has a way to generate state machine diagrams in the spec with Mermaid. I don't think it can be auto generated like we hoped, but the code to make the diagram may be easier to write than doing it in Google Sheets. Much of it can be pulled from the table we have showing the states and event transitions.

https://mermaid.js.org/syntax/stateDiagram.html