geonetwork / geonetwork/core-geonetwork
Update rst-writer.xsl to markdown-writer.xsl
- Dominant language
- Java
- Stars
- 521
- Forks
- 514
- Avg merge
- 6d 13h
- Merged PRs (30d)
- 19
Description
**Is your feature request related to a problem? Please describe.**
The [rst-writer.xsl](https://github.com/geonetwork/core-geonetwork/blob/main/docs/schema-doc/src/main/resources/rst-writer.xsl) was used to prep schema definitions for inclusion in the manual Annexes section. With the documentation being converted to Markdown this file should be replaced.
* sphinx-build: https://geonetwork-opensource.org/manuals/4.0.x/en/annexes/standards/dublin-core.html
* mkdocs: https://jodygarnett.github.io/core-geonetwork/annexes/standards/dublin-core/
See https://github.com/geonetwork/core-geonetwork/issues/7286
**Describe the solution you'd like**
The existing script can be adapted.
**Describe alternatives you've considered**
I have presently included the generated rst files as part of the conversion to markdown content, however that is not a great long term approach.
**Additional context**
The **rst-writer.xsl** made heavy use of sphinx-build references to allow other documents to link to generated content.
This facility is not available in **mkdocs**, although a file **anchors.txt** is provided as a possible workaround.
An idea I had was to:
1) Make the conversion to markdown
2) During conversion echo each reference to standard out, or include as a html comment
3) Process this information into **anchors.txt** so it can be used to update any pages referencing generated schema information
The goal is to determine an absolute URL that can be used to reference the content.
* sphinx-build: https://geonetwork-opensource.org/manuals/4.0.x/en/annexes/standards/dublin-core.html#dublin-core-elem-dc-description-8918d5eea5202286bfa9ceaac948b704
* mkdocs: https://jodygarnett.github.io/core-geonetwork/annexes/standards/dublin-core/#dublin-core-elem-dc-description-8918d5eea5202286bfa9ceaac948b704
Presently we have:
* rst
```rst
.. _dublin-core-elem-dc-description-8918d5eea5202286bfa9ceaac948b704:
Description
===========
``
* sphinx-build generated HTML
```html
Description¶
```
* Markdown:
```markdown
### Description {#dublin-core-elem-dc-description-8918d5eea5202286bfa9ceaac948b704}
```
* mkdocs generated HTML
``` html
Description
```
This is a nice to have, there are not that many references to manage.
Contributor guide
Research direction
Start with docs/schema-doc/src/main/resources/rst-writer.xsl and review issue 7286 for the Markdown conversion context. Compare the generated RST and Markdown examples, then inspect how anchors.txt could capture references; done means the existing conversion is replaced with Markdown output and the remaining schema links have a workable absolute-URL mapping.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- build-system, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100