marian-dev icon indicating copy to clipboard operation
marian-dev copied to clipboard

Move user documentation to this repository

Open snukky opened this issue 3 years ago • 2 comments

Currenlty the user documentation (https://marian-nmt.github.io/docs/) is in the repository with Marian website (https://github.com/marian-nmt/marian-nmt.github.io/blob/jekyll/docs/index.md). It would be better to have all documentation in the same repository where the code is, which hopefully will help to keep it more up to date. Sphinx supports markdown, so most of the content can be re-used.

A proposed approach for making documentation releases is first building both user + code documentation from marian-nmt/marian-dev/doc/, generating the HTML files, then copying them to the website source files in marian-nmt/marian-nmt.github.io, and finally building the website as usual with docs included. It means we will still keep a separate website repository, maybe with marian-dev as a submodule.

Ideally, we could keep the documentation consistent with the website, but that would require implementing a new theme in Sphinx (maybe it is not that difficult/time consuming?). Edited: this theme https://accentdesign.github.io/karma_sphinx_theme/ already looks quite similar to what we have on the website.

snukky avatar Mar 01 '21 11:03 snukky

Just noting that we would still need to keep marian-nmt/marian-nmt.github.io in place for the URL.

graemenail avatar Mar 01 '21 11:03 graemenail

I updated the description to make the proposed approach clearer.

snukky avatar Mar 01 '21 12:03 snukky