search

usdot-jpo-ode / wzdx

The Work Zone Data Exchange (WZDx) Specification aims to make harmonized work zone data provided by infrastructure owners and operators (IOOs) available for third party use, making travel on public roads safer and more efficient through ubiquitous access to data on work zone activity.
Creative Commons Zero v1.0 Universal
92 stars 62 forks source link

Auto-generate a PDF of the specification content #282

Closed j-d-b closed 1 year ago

j-d-b commented 2 years ago

Background

Some agencies prefer a single PDF rendering of the specification content rather than navigating the GitHub repository.

See #258 discussion for more background on the issue.

Issue

Manually create a PDF, as has been done for past specification releases, is time-consuming and error-prone as it does not go through the same review process as every line of code/documentation that is added to the repository.

Potential Solution

Create a process (could use GitHub Actions) to auto-generate a PDF of the specification from the Markdown files in the spec-content directory.

benafischer94 commented 2 years ago

@j-d-b , has a place been identified yet to house the built PDF rendering? I'd be willing to do some of the legwork to help get the action built to generate a PDF, could also do a read-the-docs version as well. I'd recommend using restructured text and a build system like sphinx to generate both the PDF and RTD version. This would allow getting styling similar to what is currently in #258.

A mixture of autodoc/autoapi and static restructured text would help reduce the amount of effort required to keep docs up to date, and allow for stylization. I would just avoid keeping built docs in the repository as it can start to take a lot of space compared to having the rst files, and a build process that's documented.

j-d-b commented 2 years ago

@benafischer94 awesome, thank you for offering to take this on.

We don't have anywhere to store files at this point, but I'd imagine much of the work is just writing the process to be able to build the PDF, so we can discuss how that build process is triggered and where the result goes later on, as long as you have all you need to get started.

j-d-b commented 1 year ago

Closed due to being a large effort balanced with limited interest.