drolbr / overpass-doc

The user manual for Overpass API
https://dev.overpass-api.de/overpass-doc/
MIT License
8 stars 10 forks source link

Consider using MkDocs to generate the documentation #13

Closed tordans closed 1 year ago

tordans commented 2 years ago

I read about MkDocs in https://github.blog/2021-12-03-release-radar-nov-2021/

Documentation is something everyone needs to think about when creating software. Good documentation helps developers and users understand what your product does, troubleshoot, and more. Material for MkDocs takes your markdown files and creates a branded static site for your documentation. The latest version supports lots of new features such as code annotation.

This looks like a quick and not too time consuming way to add search, styling and a general page layout to docs. It also supports multi language, from what I read https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/?h=language#site-language.

Screenshot with language switcher

mmd-osm commented 2 years ago

I proposed the same in #4 and i still think it would be a good idea.

drolbr commented 2 years ago

It does not look like it is worth the effort.

Apparently, the by far biggest block of extra languages is to do the translation. Or at least proofread a machine translation. For the layout frills, basically all sites by such frameworks I have seen look awkward on mobile. Thus, it remains the search function. Given the performance of Wikipedia's search, I'm again not convinced that this adds value over a simple Google search with site:dev.overpass-api.de/overpass-doc/.

matkoniecz commented 1 year ago

@drolbr drolbr added the wontfix label Aug 5, 2022

maybe closing issue would make sense?