Use material design theme for documentation, auto-deploy to Github Pages

[leonardehrenfried]

As discussed in the developer meeting, this PR changes the theme of the documentation to material which deals with nested hierarchies much better than the default and has built-in search capabilities.

It also uses the plugin mike to create a version switcher.

Here is what it looks like:

I've deployed it to my personal repo fork, so you can look at it: https://leonardehrenfried.github.io/OpenTripPlanner/dev/BuildConfiguration/

It also automatically deploys the documentation to Github Pages, which we eventually want to switch to. I expect there to be a fine-tuning period so it will not immediately become the canonical doc reference. The nice thing about using GH Pages is that we don't have to manage yet another set of access credentials: if you have access to the repo, you can also change the documentation.

@abyrd You've expressed an interest in getting rid of the ReadTheDocs service, so you might want to review this.

[codecov-commenter]

Codecov Report

Base: 60.48% // Head: 60.49% // Increases project coverage by +0.01% 🎉

Coverage data is based on head (c4e1f61) compared to base (e011673).
Patch coverage: 37.60% of modified lines in pull request are covered.

Additional details and impacted files

@@              Coverage Diff              @@
##             dev-2.x    #4575      +/-   ##
=============================================
+ Coverage      60.48%   60.49%   +0.01%     
- Complexity     12131    12186      +55     
=============================================
  Files           1577     1582       +5     
  Lines          63241    63334      +93     
  Branches        6993     6989       -4     
=============================================
+ Hits           38252    38315      +63     
- Misses         22804    22839      +35     
+ Partials        2185     2180       -5     

Impacted Files	Coverage Δ
...ntripplanner/ext/siri/SiriAlertsUpdateHandler.java	68.54% <0.00%> (+0.22%)	⬆️
...pplanner/ext/siri/SiriTimetableSnapshotSource.java	0.00% <0.00%> (ø)
...opentripplanner/ext/siri/SiriTripPatternCache.java	0.00% <0.00%> (ø)
...t/siri/updater/azure/AbstractAzureSiriUpdater.java	0.00% <0.00%> (ø)
.../opentripplanner/netex/index/NetexEntityIndex.java	99.01% <ø> (ø)
...ipplanner/netex/loader/parser/FareFrameParser.java	0.00% <0.00%> (ø)
...pentripplanner/netex/mapping/TariffZoneMapper.java	44.44% <ø> (ø)
...opentripplanner/ext/siri/SiriFuzzyTripMatcher.java	18.38% <13.33%> (-0.54%)	⬇️
...entripplanner/netex/mapping/TripPatternMapper.java	74.01% <55.55%> (-1.41%)	⬇️
...anner/netex/loader/parser/NetexDocumentParser.java	84.31% <60.00%> (-3.19%)	⬇️
... and 84 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[leonardehrenfried]

I spoke with @abyrd and he asked for the compiled HTML not to be in the same repo, even not on another branch.

I will test if I can get the CI to deploy it to another repo.

[leonardehrenfried]

@abyrd I've taken another look at this and have figured out a way to deploy this to a separate repo https://github.com/opentripplanner/docs-experiment

The compiled HTML is then viewable here: https://www.opentripplanner.org/docs-experiment/

Does this alleviate your concerns?

[abyrd]

I spoke with @abyrd and he asked for the compiled HTML not to be in the same repo, even not on another branch.

I was just observing that as a matter of form or style, it was debatable to store results of the build in the source repo that produced them. The same concerns would apply for checking in generated code, or JAR files output from source in the same repository etc.

This could potentially bloat the repo. For example if documentation source includes binary resources like images, and those get copied into the output documentation (and potentially not deduplicated). Even if this doesn't happen now, it could start happening without anyone immediately noticing in the future. This could rapidly increase the total size of all the objects in the repo, and once items are in the history a git repo they will be repeatedly cloned by each new contributor until some kind of destructive cleanup operation is performed.

But I wouldn't go as far as insisting that documentation generation be done differently - if it's much more convenient to keep everything in one repo, or it can be shown not to continuously increase repo size over time, or there's no other feasible option then I didn't intend to block it.

Fortunately it looks like you found another way. The output looks good. If you don't find the setup too complex or hard to maintain then yes, this seems like a good way to do it.

[leonardehrenfried]

We agreed at today's meeting that we want to keep the URLs exactly the same so I've adjusted build step and moved stuff around the docs repo.

Here is the new preview URL: https://www.opentripplanner.org/docs/en/dev-2.x/

@abyrd and I will migrate the DNS entries.

[leonardehrenfried]

Since readthedocs made a terrible change to their default theme, Andrew and I went ahead and moved it sooner than expected.

The new version of the docs is now available at: http://docs.opentripplanner.org/

Who can do the review for this PR?

[abyrd]

I think this round of changes could be considered complete. We've got the newly-themed docs up at docs.opentripplanner.org, and on a read-through it looks good to me.

However, it would be good to have a second look from someone on the reviewer team.

Carrying over some comments from the Gitter chat for future reference (these items are not critical and could be dealt with in some future round of changes):

On layout: the menu items (home, about, usage...) appear on a second row with quite a lot of space between the first row (OpenTripPlanner 2...) and second row. It feels like this is eating up an unusual amount of vertical space. If it's adjustable we might want to compress it down. (Or maybe the whole menu could just be in the left sidebar, see below).

The transition from a full menu display to an adaptive mobile-friendly layout occurs somewhere around 85% of my display width. This means that the "hamburger menu" appears when making the window only slightly narrower than full-width. Given that those menu items are on a second row, the transition to hamburger menu could occur only at much narrower width of say 40% and less.

It would be preferable to have a menu style where the menus for all sections were grouped together in a single left sidebar. @leonardehrenfried showed me something like this and it looked good. Without it, I feel like I have to do a lot more clicking to find the section I want. It would also reduce the discrepancy between the full-width version of the pages and the adaptive narrower version with the hamburger menu.

[leonardehrenfried]

@abyrd I've deployed the navigation version without tabs to the dev-2.x version: https://docs.opentripplanner.org/en/dev-2.x/

Here is what I suggest we do:

• we review and merge this PR (you and someone else need to re-approve)
• you review the navigation of the dev-2.x version of the docs for maybe a week or so
• if you're satisified i can rebuild the docs for the other versions (1.5 - 2.2)

The last step is a bit labour-intensive so I want to avoid doing it several times that's why I ask for the weeklong review.