Do not publish documentation on GitHub pages
e-pettersson-ericsson opened this issue · 1 comments
Description
Currently we have documentation for Eiffel Intelligence located in the source code repository, which is also published on GitHub pages for every Travis build on master. We write the documentation in markdown and then convert to HTML to publish on GitHub pages. Because we render HTML from the markdown pages the links can not be relative (since maven site plugin does not handle those). Because we are forced to use full links and not relative links in the markdown this means we do not benefit from GitHub's version handling of the documentation.... This causes problems for users reading the documentation for a specific git tag (a previous release) and follow a link to the next page (which is hard-coded to master) and the documentation is not accurate anymore.
This goes for both Eiffel Intelligence back-end and front-end, and I've written a separate issue for front-end: eiffel-community/eiffel-intelligence-frontend#237
Motivation
In order to benefit from GitHub version handling of documentation located in the repository, we need to use relative links in our markdown files. As a consequence we can not utilize the maven site plugin to render HTML pages and publish on GitHub pages (since the links will break there).
I propose we remove the maven site plugin (conversion of markdown to HTML) and instead always use relative links in markdown files so it's easy for the user to go to a specific version of the source code and read the documentation for that.
Exemplification
To select previous versions of the documentation, users can select whichever git tag they want to see the documentation for, as seen in the picture below.
What needs to be done?
- The Travis file needs to be updated to remove the deploy job
- Remove the maven site plugin dependency
- Fix all links in the documentation to be relative
Benefits
We utilize the version handling of markdown files using GitHub. It will be easier for users to find the correct version of the documentation and not be redirected by links referring to latest on master all the time.
Possible Drawbacks
We do not publish on GitHub pages anymore. But then again, it will be easier to maintain the documentation if it's only in markdown files in the repository.
Closing this issue since the code changes have been merged.