Porting Switch2OSM to MkDocs from Jekyll

[Andygol]

This PR closes #224.

If necessary, the translation of texts can be organized through the integration with Transifex (use transifex.yml)

Feel free to adjust this PR if needed.

PS This is a newly reproduced PR #244. See previous discussions there.

[pnorman]

This has the same issue as the previous PR where it's mixing changing to MkDocs, adding translation support, adding specific language translations, content changes (e.g. new images), and contribution guideline changes.

Shouldn't the translations live in transifax and be pulled by a build process?

[Andygol]

In my working demo repo https://github.com/Andygol/switch2osm-mkdocs translation process goes via Transifex and you may establish the same routing using included transifex.yml by getting translated materials via Transifex automation.

[pnorman]

Re-reviewing as requested.

The line-by-line comments have been addressed except about if osm-ua is the right org, but the overall comments that prevent a more detailed review remain.

This has the same issue as the previous PR where it's mixing changing to MkDocs, adding translation support, adding specific language translations, content changes (e.g. new images), and contribution guideline changes.

Shouldn't the translations live in transifax and be pulled by a build process?

[Andygol]

Shouldn't the translations live in transifax and be pulled by a build process?

I kindly suggest reaching out to the proper OpenStreetMap (OSM) Working Group to explore the possibility of receiving assistance in implementing support for translations on Transifex within the framework of the OSM organization. This could greatly streamline the translation process for the broader community, should you be interested in pursuing this enhancement.

[Andygol]

Hello everyone,

It appears that progress on the transition to a new platform is currently stalled. To facilitate progress, I propose the following course of action:

• Rename the current repository to something like "switch2osm-jekyll-arch" and archive it for preservation as a historical artifact.
• Create a new repository named "switch2osm" where the code from my existing repository (https://github.com/Andygol/switch2osm-mkdocs) will be transferred, either through forking or simple copying. Starting afresh on the mkdocs platform, we can then integrate it with Transifex to support translations and encourage broader community involvement.

If this plan seems viable, let's proceed with its implementation!

[SomeoneElseOSM]

Firstly - thanks for all your hard work here!

If this plan seems viable, let's proceed with its implementation!

As @pnorman mentioned earlier, this PR tries to do about three different things at once:

• move from jekyll to mkdocs
• add support for translation
• content changes, including adding some new "vector tile" pages

Taking these one at a time:

I've had a play around with the mkdocs versions of the pages and it seems to be easier to set up, easier to customise and more flexible with regard to formatting than jekyll - it's definitely worth moving to mkdocs for those reasons. When I tested it it was easy to deploy as a static site, so I'd imagine @Firefishy wouldn't have problems setting that up (availability of time notwithstanding).

It's not yet clear to me how the translation will work. Is the idea that initially the site is deployed statically without "live" translation (but with just a couple of pre-translated language versions) and later someone sets up translations via a service such as Transifex? That's how I read the initial comment "If necessary, the translation of texts can be organized through the integration with Transifex (use transifex.yml)". I'm not familiar with how that would work, and it'd probably be easier (as @pnorman suggested to try and do one thing at once) - move to mkdocs, and add translation later. To be clear - translation into whatever languages people are prepared to support is absolutely something that we should be doing, but we do need to understand how.

It's clear that this site is already well overdue for content changes that cover vector tile options. The priority eventually will be "whatever is available on openstreetmap.org", which I believe is going to be based on https://github.com/pnorman/tilekiln , see openstreetmap/operations#1073 and openstreetmap/operations#565 . However, there are a bunch of other vector tile approaches that people are using right now that ought to be covered too.

Eventually (and this really should be a separate PR after everything's comfortably in mkdocs and we've decided how and if to do translation) I think we'll want a top-level split on both the "using tiles" and "serving tiles" sides between "vector" and "raster" (and possibly other approaches - e.g. for Garmin). If osm.org starts serving vector tiles based on the shortbread schema then lots of people are going to want to try "using tiles" and need to understand what is in and what is not in that schema. We'll also want to cover the "serving tiles" and "using tiles" approaches used by some of the current higher profile projects such as OSM Americana.

One problem with the vector tile pages in this PR such as this is that there isn't really the level of detail that someone who is new to the process can follow. Compare "You can use tools like osm2pgsql or imposm to import OSM data into a database" on that page with the equivalent instructions on one of the raster map pages. I've tried in the past to find something that isn't dependent on a proprietary service, can be self-hosted and is well-documented, and the best I've found is the documentation around tilemaker. In contrast, with shortbread I fell at the first hurdle trying to set it up, although things may have improved** since I looked (e.g. via inclusion in osm2pgsql-themepark).

Some of the other content changes (e.g. the links in the mkdocs footer) could probably benefit from minor tweaks, but I'm sure that'll be easy to do in an mkdocs-only PR.

** edit: a quick check suggests they have.

[matkoniecz]

currently stalled

Note

the overall comments that prevent a more detailed review remain.

This has the same issue as the previous PR where it's mixing changing to MkDocs, adding translation support, adding specific language translations, content changes (e.g. new images), and contribution guideline changes.

In other words, it would be more actionable if single PR would not mix several big changes.

Would it be feasible to split it in parts?

[Andygol]

One problem with the vector tile pages in this PR such as this is that there isn't really the level of detail that someone who is new to the process can follow.
…
** edit: a quick check suggests they have.

@SomeoneElseOSM feel free to contribute to https://github.com/Andygol/switch2osm-mkdocs

[Andygol]

Mateusz and Paul, thanks for the advice on this PR. However, the problem is not in how it should be divided or organized, but in the global intention. For my part, I showed a working example (https://andygol.co.ua/switch2osm-mkdocs/) and concept (https://github.com/Andygol/switch2osm-mkdocs, https://app.transifex.com/osm-ua/swtch2osm/dashboard/#/). On the part of the maintainers, I expect certain steps towards its adaptation or a statement that this will not be done. In addition to this PR, I proposed an action plan (#248 (comment)) that only maintainers can perform.

• Rename the current repository to something like "switch2osm-jekyll-arch" and archive it for preservation as a historical artifact.
• Create a new repository named "switch2osm" where the code from my existing repository (https://github.com/Andygol/switch2osm-mkdocs) will be transferred, either through forking or simple copying. Starting afresh on the mkdocs platform, we can then integrate it with Transifex to support translations and encourage broader community involvement.

If this plan seems viable, let's proceed with its implementation!

PS
@grischard @Firefishy what do you think about starting a project at https://switch2.osm.org (go2.*, move2.*, run.* — anything you want)?

[SomeoneElseOSM]

@SomeoneElseOSM feel free to contribute to https://github.com/Andygol/switch2osm-mkdocs

https://www.openstreetmap.org/user/SomeoneElse/diary/404191 is my first take on the level of detail required. Hopefully someone will be able to follow that rather than, say, "Make sure you have Node.js installed on your system".

That's far from the finished article though (and as mentioned above anything for the switch2osm site would be better with separate "creating vector tiles" and "showing the output for the user"). Just writing that identified a few rough edges in the existing documentation (see my recent PRs).

I'm not convinced that someone who "just wants to serve some vector tiles on their web site" would want to use a special web server just for that, whether that's VersaTiles' one or TileServer-GL (though of course there will be niches for both of those), so I went with Apache and "mod_mbtiles".

However, the problem is not in how it should be divided or organized, but in the global intention

"How to get from here to there" is key to the process. Something that looks nicer, might support translation in the future (but it isn't explained how, yet) and contains some new pages that definitely need further work is a really useful demonstrator, but isn't something that can be merged as a whole.

[pnorman]

As noted by Andy

I've had a play around with the mkdocs versions of the pages and it seems to be easier to set up, easier to customise and more flexible with regard to formatting than jekyll - it's definitely worth moving to mkdocs for those reasons. When I tested it it was easy to deploy as a static site, so I'd imagine @Firefishy wouldn't have problems setting that up (availability of time notwithstanding).

Based on this I'm okay with moving to mkdocs. Can you prepare a PR that does that without unrelated changes?