Streamlining website and documentation

[naskio]

Description

This issue tracks improvements for our website (https://armadaproject.io/) and documentation.

Current Challenges

The current website and documentation setup presents several hurdles:

• Maintaining Consistency: Keeping documentation in sync across the master and gh-pages branches is cumbersome and prone to inconsistencies. (related issue: #3715)
• Outdated Content: The website includes pages that are no longer part of the current documentation. (for example: https://armadaproject.io/developer/aws-ec2.html)
• Broken Links: Many website links are broken (for example: https://armadaproject.io/developer/etc-localdev.md).
• Deployment Limitations: Absolute URLs prevent deployment on forks (related issue: #1105).
• Manual Updates: Protection rules necessitate manual pull requests for syncing files between branches (related issue: #3715).

Solution

1. Move Website Source Code to Master: Relocate the website source code from the gh-pages branch to a dedicated website/ folder within the master branch. This consolidates all source code into a single branch, streamlining the workflow and helps overcoming GitHub limitations related to protection rules and GitHub Pages. #4163

2. Centralized Documentation: Consolidate all documentation into a single source using Markdown format. This centralized approach simplifies maintenance, updates, and accessibility from the GitHub UI, IDEs, and the website itself. #4164

3. Documentation Validation: Implement a workflow to validate the documentation and ensure there are no broken links.

4. Enabling Fork Deployment: Employ relative links to allow developers to work on their forks and facilitate website preview for maintainers before merging.

5. Automated Workflows with GitHub Actions: Leverage GitHub Actions to automate documentation validation, website building, and deployment whenever changes occur in the documentation or website source code. This ensures the website remains consistently up-to-date.

[Sonichigo]

Hey @naskio if there's still scope left, can i also take part in resolving this issue?

[suprjinx]

Hey @naskio if there's still scope left, can i also take part in resolving this issue?

I don't think we've fully resolved this yet.

1. there is not a /website folder in master which contains the content of the gh-pages branch.
2. the CI workflows are not working. gh-pages is a protected branch so it needs to be updated by approved PR.
3. the markdown docs and in-line code docs are processed and linked in a confusing way. I'd suggest we just have an HTML website that links to documentation which is pure markdown rendered by github in the repository (?). In-line docs should probably be something like swagger.

[naskio]

Hi @suprjinx, We're currently working on a new version of the website, which is available for preview here: https://naskio.github.io/armada/ The code is available on my fork: https://github.com/naskio/armada (still WIP) Most of the existing documentation in the current docs/ folder is outdated and needs to be reworked.