geonetwork / geonetwork/core-geonetwork

Update rst-writer.xsl to markdown-writer.xsl

Open
#7,342 0 comments 0 reactions 0 assignees View on GitHub
Documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.