Closed jodygarnett closed 9 months ago
Code sprint notes:
help
online help for anonymous users, end-user focused content with no cross links to adminmanual
port of sphinx-build docs (does not conflict with manuals
git submodule)Discussion:
Note we will need to wish to update the sample data for screen snaps (some web services have changed and we need an update in order to have working Add to map demo):
It would be nice to add an extra menu to the GeoNetwork menu bar that points to parts of the documentation.
There is a link in the footer presently and a build option to include docs in release.
I hope we can include a small “online help”’for visitors. If we do the online help doc theme right it can pick up the logo of the running geonetwork and have a similar menu bar appearance.
Okay the script is doing great for converting files unattended, however references are a pain to update manually.
Looks like we have 366 items to update:
grep --include=\*.rst -rnw . -e ":ref:`.*`" | wc -l 366
Reviewing examples:
./overview/change-log/version-3.10.1.rst:10:* CSW / Configuration of the capabilities is now done using a service metadata record :ref:`csw-configuration`
./annexes/standards/dublin-core.rst:25:* :ref:`dublin-core-view-default`
./annexes/standards/iso19115-3.2018.rst:121:See :ref:`iso19115-3.2018-elem-mdb-identificationInfo-7b3f7b7fbb8a986c92658058fe54f876`
So while may end up being links to page, or header, references. The last example seems unnecessarily difficult!
The online manual has https://geonetwork-opensource.org/manuals/4.0.x/en/annexes/standards/iso19115-3.2018.html?#iso19115-3-2018-tab-identificationinfo
The annexes/standards/iso19115-3.2018.rst
source has:
.. _iso19115-3.2018-elem-mdb-identificationInfo-7b3f7b7fbb8a986c92658058fe54f876:
Identification info
===================
:Name:
mdb:identificationInfo
:Description:
.. raw:: html
Basic information about the resource(s) to which the metadata
applies
So something seems off, perhaps these things linked to the external
How many anchors do we have:
grep --include=\*.rst -rnw . -e "^.. _.*:$" | wc -l
2105
Well that is intimidating:
./api/index.rst:1:.. _api-guide:
./overview/change-log/version-3.10.7.rst:1:.. _version-3107:
./annexes/standards/dublin-core.rst:164:.. _dublin-core-elem-dc-contributor-0974cafd6cf5302fe8501874dbe3b3ac:
The vast majority are in the annexes, most of the other are simple page lookup.
Processing by hand:
grep --include=\*.rst -rnw . -e "^.. _.*:$" > anchors.txt
Grep search and replace (I used an editor):
^\./
-->
^([\w\-/\.\d_]+)\.rst:\d*\:\.\.\s+_([\w\-\d_\s\./]+):$
--> \2=/\1.md#\2
Result anchor=absolute markdown reference
toc=/index.md#toc
administrator-guide=/administrator-guide/index.md#administrator-guide
...
With one leftover:
annexes/standards/iso19139.rst:24731:.. _iso19139-cl-gmd-MD_ScopeCode-/ancestor--node()[name()='gmd-MD_Metadata']/gmd-identificationInfo/srv-SV_ServiceIdentification:
See attached: anchors.txt
@jodygarnett some documentation pages are created from the schema plugins
So Annexes > Standards > * and https://geonetwork-opensource.org/manuals/4.0.x/en/customizing-application/editor-ui/creating-custom-editor.html can probably be excluded from your scripts and we can probably replace rst writer by the new format in https://github.com/geonetwork/core-geonetwork/tree/main/docs/schema-doc/src/main/resources
Well this is disheartening - @MichelGabriel updated the version of mkdocs-i18n-static to version 1.0.x and we have encountered a bug: https://github.com/ultrabug/mkdocs-static-i18n/issues/258
I do hope these plugins do not change often, but I was using a <1.0 release of mkdocs-18n-static so change should be expected.
I think the nice thing to do for now is to leave the files as text, and include them in one big long change log. Renaming the files would be unpleasant.
The PR is now code complete, preview available for visual review here https://jodygarnett.github.io/core-geonetwork/
We can probably replace rst writer by the new format in https://github.com/geonetwork/core-geonetwork/tree/main/docs/schema-doc/src/main/resources
Thanks for that information - ticket here: https://github.com/geonetwork/core-geonetwork/issues/7342
It looks like some of the relative links are broken, they always point to the file in the same directory, which is not always the case and the named anchor seems to end up in the filename somehow.
Updated the bug description, all links are fixed and the build is clean with no warnings.
I am getting private feedback on content - I would prefer of content updates are in a second pull request.
I enabled the language chooser, but here is some strange interaction with using mike to publish versions. I opened a ticket here https://github.com/ultrabug/mkdocs-static-i18n/issues/265 in hopes of guidance.
Update: resolved by reading the manual (site_url was required)
I think this ticket can now be closed?
Meeting
Demo / discussion:
mike
was cool, but more research needed. Open question how to have 4.4-SNAPSHOT docs? latest redirects to 4.2.5 and is not separateDecisions:
merge planning:
http://docs.geonetwork-opensource.org
just before mergeFinal Review Update
Review:
mike
plugin (see readme below)How-to included in PR:
IMPORTANT:
Code-complete update
Preview available here https://jodygarnett.github.io/core-geonetwork/
We are interested in review of the content
Want to ensure the xml and javascript code examples are not harmed in the transition for example
The docs are now pretty much 100% convertible using Jody's translate script wrapper on pandoc:
With this script working so well it is now "easier" to fix the sphinx-build content to correct formatting for indenting, accidental block quotes and the like.
For later:
Initial code-sprint proposal
The following work is proposed: https://github.com/geonetwork/core-geonetwork/wiki/Proposal-mkdocs.md
docs/
folder to directly manage user-manual alongside codebase (PRs changing UI required to change docs.)translate
script provided to automate the creation of new translation files using deepl (even if it just provides a starting point that is fine)Keep in mind:
Compare:
Example page: