Replace GitHub Pages through README

[PatrickGotthard]

The current "GitHub Pages" Page is completely outdated.
I think that maintaining a seperate documentation beside the README is time-wasting and does not work.
I propose to clean up the documentation and to write everythink into the README.

What do you think @mishako / @imk ?

[PatrickGotthard]

Do you have an opinion about this? @antoniosanct @neroux @rome-user

[neroux]

I'd argue a proper website can present the information in a more structured and user-friendly way than just one long text file. That is assuming, of course, the README version should still contain a similar set of information. IMHO, first decide on the content and then how you'd like to structure it.

And yes, an update of the site might be a good idea, as some of the documents (e.g. version 2) are coming of age :)

[PatrickGotthard]

I've just converted the old documentation from apt to markdown and I'll figure out how to publish the docs in release-specific folders on the gh-pages branch. After that I'll publish the current docs one last time and then clean up everything rigorously.

[rome-user]

I agree with neroux. The website is useful because it can contain a lot more information than a README. For maintenance, it would be a good idea to have a bunch of markdown files in a gh-pages branch. Let us know when everything's ready; I wouldn't mind opening PRs to update the site documentation :)

[PatrickGotthard]

I've tested https://readthedocs.org today and think that this will be a good platform for our new documentation. Also I just finished to give the existing documentation some structure (was a big mess) :)

Now I'll cleanup the documentation, create a polished documentation for 1.x and 2.0 and new documentations should be automatically generated for every new release.

[PatrickGotthard]

I'm currently thinking about the pros and cons between (1) integrating the docs into the rome repository vs (2) having a seperate repository for the documentation.

Option 1)

• (pro) new docs will be published automatically when a new release will be created
• (pro) the docs are tied to the release version
• (con) difficult to fix documentation after creating the release

Option 2)

• (pro) you have to release a new documentation every time a new release comes out (maybe this could be automated using some GitHub Actions magic)
• (pro) the docs are not tied to a rome release
• (con) easy to fix documentation afterwards

What do you think?

[neroux]

I would probably go for 2.

Why would you want to tie the documentation to individual releases?

[PatrickGotthard]

I would probably go for 2.

Why would you want to tie the documentation to individual releases?

I took that inspiration from Spring (I'm a huge Spring fan 😜). But I also think Option 2 will be sufficient and more flexible for now.

[PatrickGotthard]

It took me many hours, but here's the first draft now: https://rome.readthedocs.io/en/latest/

And here's the according repository: https://github.com/rometools/rome-docs

I still have to revise many pages but foremost I hope the new structure is helpful and intuitive.

[antoniosanct]

Hi, @PatrickGotthard
An absolutely and incredible work here! Congratulations!
Regards,
Antonio.