Documentation within TDM code

6 posts / 0 new
Last post
bhereth
Documentation within TDM code

Has anyone implemented or otherwise come across an elegant approach to integrating highly-structured descriptive comments (perhaps using markdown, json, etc) into your travel demand model scripts so that text-based or graphical documentation can be harvested from the code itself (and documentation can be maintained explicitly within the code)?

Similarly, we are curious what diagramming or schematic software you have used for visual documentation outside of travel model platforms.

elizabethsall

Personally, I really like using MkDocs , which is
built in python, but you can add a plug-in for most code-types.

A project that I'm involved in (but can't take credit for) uses it
extensively for documentation generation as seen here:
https://docs.calitp.org/data-infra/intro.html
Some features I really like:
- mermaid - based charts for UMLs,
processes, etc (note: you can do this in github flavored markdown now too!)
- plug-ins (i.e. mkdocstrings ) for
documenting in-code docstrings
- mike to manage multiple versions
based on github branches
- you can deploy it without thinking too hard when you push to github using
a github workflow (see last lines of this example

)

YAY for self-documenting code!

On Thu, Aug 4, 2022 at 1:05 PM bhereth wrote:

> Has anyone implemented or otherwise come across an elegant approach to
> integrating highly-structured descriptive comments (perhaps using markdown,
> json, etc) into your travel demand model scripts so that text-based or
> graphical documentation can be harvested from the code itself (and
> documentation can be maintained explicitly within the code)?
>
> Similarly, we are curious what diagramming or schematic software you have
> used for visual documentation outside of travel model platforms.
> --
> Full post: https://tmip.org/content/documentation-within-tdm-code
> Manage my subscriptions: https://tmip.org/mailinglist
> Stop emails for this post: https://tmip.org/mailinglist/unsubscribe/13833
>

bwen

 

I also use MkDocs. It fulfills most if not all of the uses of Sphinx, plus it uses markdown instead of LaTeX, which I personally find more intuitive to learn and write in. As Elizabeth already mentioned, you can use a number of plugins with MkDocs to add/make charts, generating references with python docstrings, and even manage multiple versions with mike (we have recently started experimenting with this). We use MkDocs to compile our model documentation into html, and automatically deploy it on github.io: https://github.com/TransLinkForecasting/rtmdoc

As for diagram, I use draw io. It's open source. It saves your work as xml and is able to export into vector graphics like svg. https://github.com/jgraph/drawio

 

kywyjusin

Hello Bill,
It's not yet complete, but MTC (with assistance from WSP and UrbanLabs) is
implementing their travel model as a Python package, which allows us to
leverage all the useful documentation features of Python. The repository is
here (where the work will continue)
and example documentation is here
, including diagrams of the
software architecture
.
thanks.

On Thu, Aug 4, 2022 at 4:05 PM bhereth wrote:

> Has anyone implemented or otherwise come across an elegant approach to
> integrating highly-structured descriptive comments (perhaps using markdown,
> json, etc) into your travel demand model scripts so that text-based or
> graphical documentation can be harvested from the code itself (and
> documentation can be maintained explicitly within the code)?
>
> Similarly, we are curious what diagramming or schematic software you have
> used for visual documentation outside of travel model platforms.
> --
> Full post: https://tmip.org/content/documentation-within-tdm-code
> Manage my subscriptions: https://tmip.org/mailinglist
> Stop emails for this post: https://tmip.org/mailinglist/unsubscribe/13833
>

amparaj

Hi, we are using Sphinx for our transport model documentation of our python scripts and config files (most of which are yaml format that allows structured descriptive comments).

kywyjusin

Correction/addendum to my previous post: Bentley and W&S Solutions are also
on the team supporting the MTC work. Shout out to Kevin Bragg, one of the
lead engineers on the project.
thanks.

On Fri, Aug 5, 2022 at 6:50 AM amparaj
wrote:

> Hi, we are using Sphinx for our transport model documentation of our
> python scripts and config files (most of which are yaml format that allows
> structured descriptive comments).
> --
> Full post: https://tmip.org/content/documentation-within-tdm-code
> Manage my subscriptions: https://tmip.org/mailinglist
> Stop emails for this post: https://tmip.org/mailinglist/unsubscribe/13833
>