Hì Jody, I'm all for the simplest possible approach to writing documentation, and one less syntax to master is a benefit.
Some questions: - The automation is impressive, how much work do you reckon it would be migrate GeoTools? - Could you also socialize the idea in GeoServer, so that we get more points of view? It would not be good to do a GT migration but not a GS one - I'm trying to figure out how much we'll have to compromise in terms of output, and wanted to find out how good the output would be. I know you recently did a GeoNetwork migration but I don't see the results. In particular, the current Geonetwork guide seems to be built with sphinx using the "read the docs" theme (which I find depressing and sickening, looks like a backwater python library): https://geonetwork-opensource.org/manuals/4.0.x/en/index.html The example that was linked from the Geonetwork proposal is a bit more lively, though still pretty bland: https://jodygarnett.github.io/iso19139.ca.HNAP/search/records/ Can we get something a bit more upbeat/colorful like we have today (thinking more of the Geoserver docs here)? Or are the themes hard to update? Cheers Andrea On Mon, Oct 2, 2023 at 1:00 AM Jody Garnett <jody.garn...@gmail.com> wrote: > Going to run an experiment tomorrow and have written it up as a proposal > to protect the innocent: > > - https://github.com/geotools/geotools/wiki/MkDocs > - https://osgeo-org.atlassian.net/browse/GEOT-7466 > > > If successful it would be a good time to change the format of the docs. > Due to API change I do not anticipate a lot of changes being back ported to > the maintenance branch this release cycle (so the overhead of changing from > reStructuedText to Markdown). > > If you already like Markdown you can skip the proposal and just look: > > - Compare example sphinx-build > <https://geonetwork-opensource.org/manuals/4.0.x/en/overview/index.html> > vs mkdocs <https://jodygarnett.github.io/core-geonetwork/4.2.5/> > - Structure is unchanged so existing links to the docs do not break > - Search actually works > > From the proposal: > > The Journey is tough but the destination appears worth it. > > > - Previously I learned convert content and not rewrite at the same time > - This time I learned not to edit at all and made a script > http://github.com/jodygarnett/translate > - The script uses pandoc and then cleans up the mess for any > sphinx-build directives that pandoc cannot support > - A lot of the work went into reverse engineering doc and ref > directives, > and processing toctree directives that we would not wish to do by > hand. These are all sphinx-build directives that require knowledge of > documentation structure beyond a single file. > - With such a powerful script it was often faster to fix problems > in RST and re-convert (example for unexpected block quotes due to > indenting) > > > The destination: > > > - mkdocs build is faster, and responsive when editing > - the material theme is very good and well supported > - mkdocs.yml requires a navigation tree of all pages (but there may > be a plugin to glob *.md files) > - Amazing: the search actually works > - Disappointing: We give up some explicit features (guilabel, > menuselection, file, download) and can make do with a clear writing > guideline. It seems I may of been the only person appreciating these > capabilities of sphinx-build > - Great: Some of the advanced features we enjoy like > literal-include are covered by markdown extensions > - Bonus: version management for docs is much nicer > > > Markdown is less expressive than sphinx-build, so we have to rely on a > strong writing guideline to capture conventions that are no longer enforced > by inline directives > > -- > Jody Garnett > _______________________________________________ > GeoTools-Devel mailing list > GeoTools-Devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/geotools-devel > -- Regards, Andrea Aime == GeoServer Professional Services from the experts! Visit http://bit.ly/gs-services-us for more information. == Ing. Andrea Aime @geowolf Technical Lead GeoSolutions Group phone: +39 0584 962313 fax: +39 0584 1660272 mob: +39 339 8844549 https://www.geosolutionsgroup.com/ http://twitter.com/geosolutions_it ------------------------------------------------------- Con riferimento alla normativa sul trattamento dei dati personali (Reg. UE 2016/679 - Regolamento generale sulla protezione dei dati “GDPR”), si precisa che ogni circostanza inerente alla presente email (il suo contenuto, gli eventuali allegati, etc.) è un dato la cui conoscenza è riservata al/i solo/i destinatario/i indicati dallo scrivente. Se il messaggio Le è giunto per errore, è tenuta/o a cancellarlo, ogni altra operazione è illecita. Le sarei comunque grato se potesse darmene notizia. This email is intended only for the person or entity to which it is addressed and may contain information that is privileged, confidential or otherwise protected from disclosure. We remind that - as provided by European Regulation 2016/679 “GDPR” - copying, dissemination or use of this e-mail or the information herein by anyone other than the intended recipient is prohibited. If you have received this email by mistake, please notify us immediately by telephone or e-mail
_______________________________________________ GeoTools-Devel mailing list GeoTools-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/geotools-devel
