Andrea:
1. To migrate GeoTools I need to make one major improvement to the script -> processing the include-source directives into an equivalent mkdocs extension. Material for MkDocs recommends <https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#snippets> the pymdownx.snippets extension, but it seems odd. - We include using comments in the example code, and start / before pattern matching - The --8<-- marker that looks like a pair of scissors is cute! - Snippets has a cool feature where you can *name* the snippet in the example code: // --8<-- [start:dataStore] DataStore store = DataStoreFinder.... // --8<-- [end:dataStore] And then include it using: --8<-- "include.md:name" Stack exchange recommended mkdocs-include-markdown-plugin and I got it to work: - It matches our existing workflow, but is not as cute - It provides two things include-markdown, and include (for example code) Mkdocs-macros <https://mkdocs-macros-plugin.readthedocs.io> seems to turn mkdocs into a mini templating framework and is too complicated to live - The only thing that would be good here is the ability to re-create |project| and |version| equivalents 1. I plan to socialize in GeoServer when I have a chance to define what is needed: - In addition to code examples we have some very complicated "download" external-link directive in GeoServer (with may need to be replaced with simple markdown, or worthwhile maintaining using mkdocs-macros - I can share the geotools proposal with the geotools-devel list 1. I did include the geonetwork result in the proposal and initial email. But you are correct that it was a generic sphinx-build theme ant not he best comparison. - Sphinx-build generic theme: https://geonetwork-opensource.org/manuals/4.0.x/en/user-guide/describing-information/creating-metadata.html - Sphinx-build read-the-docs with custom colours: https://www.geocat.net/docs/geonetwork-enterprise/2022/geonetwork/community/user-guide/describing-information/creating-metadata.html https://metadata101.github.io/iso19139.ca.HNAP/search/records.html - Material for MkDocs: https://docs.geonetwork-opensource.org/4.2/user-guide/describing-information/creating-metadata/ https://docs.geonetwork-opensource.org/4.2/help/search/ The selected "Material for MkDocs <https://squidfunk.github.io/mkdocs-material/>" (be sure to scroll down the home page). This is by far the most established and best supported theme. Indeed it is so well done it is almost a separate environment to mkdocs; and has excellent documentation. Making it "fun" is a little up to styling and getting some time from Michel 🙂 Indeed his evaluation of the different documentation options, and enthusiasm for Material for MkDocs, is a key enabler for this proposal. I fund many of the reference examples <https://squidfunk.github.io/mkdocs-material/reference/> fun: - The little icons, and the ability to define your own <https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/> - Linked tabbed code example things <https://squidfunk.github.io/mkdocs-material/reference/content-tabs/> - A big thing for geoserver could be the language chooser, and the version chooser which was a decider for geonetwork -- Jody Garnett On Oct 2, 2023 at 6:30:32 AM, Andrea Aime <andrea.a...@geosolutionsgroup.com> wrote: > 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
