Update Documentation

[teikmeout]

This PR will do the following:

• Remove policy and users docs, solves INVENIO-152
• Update docs homepage, solves INVENIO-153
• Add invenio-cli cheatsheet
• Add project orientation content and updated links
• Update Ruby Version to 3.0.5, solves INVENIO-151
• Update gem github-pages
• Update homepage Links
• Update docker documents
• Update Look and Feel documentation
• solves INVENIO-150

To test this PR make sure to:

• install newer version of Ruby with rbenv install
• install bundler with gem install bundler
• reinstall gems with bundler install --redownload
• run the project locally with bundle exec jekyll serve

To test this PR please check Github Actions pages-build-deployment to ensure it can run on this pipeline. I'm assuming that the GH action will read the .ruby-version file, but have no direct way to prove that it will build accordingly.

Thank you for our review! Please let me know if there are changes needed :)

[teikmeout]

We might want to pause this one since I'm seeing https://pages.github.com/versions/#:~:text=ruby,2.7.4 and I think it might be better to stick to what github pages is using...

[teikmeout]

Context and Motivation:

• when trying to locally setup and run this documentation on M1 mac I ran into many installation issues.
• I found that we are using an outdated Ruby version 2.7.4 (newest 2.7.7) with endOfLife date on March 2023
• I tried using Ruby 2.7.7 and installation was successful. This was a good sign. I would prefer to update out of this version into something with future support.
• I tried using Ruby 3.0.5 and after adding webrick (gem was removed in Ruby > 3) bundle install was successful. Another good sign. This is when I thought this was ready to become a PR.
• I was worried about our CI/CD pipelines not following the newer version of Ruby since we use a community Github Action. So I kept on researching.

What I have learned:

• Github pages is a Ruby + Jekyll Project that uses Ruby 2.7.4 and Jekyll 3.9.3 as of Feb 28 2023
• Github pages does not specify what version of Ruby to install either in their Test your Local Site documentation or their Create a Site documentation
• Github pages recommends using github/pages-gem that is a gem that helps setup a development environment quickly but also maps and locks a ruby version and a jekyll version. They mention this is valuable since different Ruby versions have different default tools, recommending to actually stick to older versions of Ruby and Jekyll.
• Also weirdly enough: When starting a GithubPages/Jekyll site from scratch, they instruct you to install (any) Ruby version followed by installing any version of Jekyll, only to later comment out the jekyll gem from the gemfile and replace it with the github-pages gem. This could lead to starting your site with a new Jekyll version that might be higher than the github-pages gem contains.
• Github pages in its documentation makes an inconspicuous note when running into webrick issues implying it's accounted for using Ruby > 3.0?? Yet when reading deeper into their docs you can see how their is an intention of keeping consistency in using Ruby 2.7.4 and Jekyll 3.9.3
• Funny enough Jekyll 4.3.0 already includes the webrick gem in the Gemfile making the migration to newer Ruby > 3.0 even easier.

What happens next?

• option 1: we keep this PR, update to newer Ruby for our local development setup and we deal with the inconsistencies at deployment.
• option 2: we stick to what Github pages uses for consistency and keep the current Ruby version used in this project.
• option 3: we make a PR to the Github pages repo? and try to push for newer usage of Ruby > 3 and Jekyll > 4?

Thank you for your insight and please let me know your thoughts and if you'd like me to revert the Ruby update to stick to what Github pages uses.

[VickyRampin]

I don't think anyone is tied down to using Jekyll either, so option 4 might be to abandon our current format and move the content that is relevant to Sphinx or some other more accepted docs format/tooling that has lower dependency needs.

[debverhoff]

Jonathan, Thanks for digging in and coming up with these options.

I don't have any valuable input about updating Ruby locally or otherwise, and defer to Kate et al. As per Vicky's note that we could also move to another docs tool, I think that is a fair option too. I rather like having the docs near to the code, but maybe I am overthinking that convenience when a link could suit the purpose.

What do others think? It will be good to keep momentum on this since we have some documentation in the wings.

On Tue, Feb 28, 2023 at 4:14 PM Vicky Rampin (née Steeves) < @.***> wrote:

I don't think anyone is tied down to using Jekyll either, so option 4 might be to abandon our current format and move the content that is relevant to Sphinx https://urldefense.proofpoint.com/v2/url?u=https-3A__www.sphinx-2Ddoc.org_en_master_&d=DwMCaQ&c=slrrB7dE8n7gBJbeO0g-IQ&r=XHsbA-JmWdN4BncHenIG8Wbm3JKzxA1hI4Tg4kwAbhM&m=Fbx0tt6fdV4-rO0MhCvBxeh4m4T1kfzxp6b5GhtScvnj-fMxO1pjweKR1MSAbxz-&s=RzhUbOdBZTU9PYQ9eri6P9I8IcrlWxAq22LPISI7SE0&e= or some other more accepted docs format/tooling.

— Reply to this email directly, view it on GitHub https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_nyudlts_ultraviolet_pull_174-23issuecomment-2D1448925244&d=DwMCaQ&c=slrrB7dE8n7gBJbeO0g-IQ&r=XHsbA-JmWdN4BncHenIG8Wbm3JKzxA1hI4Tg4kwAbhM&m=Fbx0tt6fdV4-rO0MhCvBxeh4m4T1kfzxp6b5GhtScvnj-fMxO1pjweKR1MSAbxz-&s=knwyZFmfG7FKdva253JxLUTKRUITX894RUKUKTkPC6w&e=, or unsubscribe https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_notifications_unsubscribe-2Dauth_AIHLKJHHAD6NEBFA3XDY64DWZZTDBANCNFSM6AAAAAAVGJVKGM&d=DwMCaQ&c=slrrB7dE8n7gBJbeO0g-IQ&r=XHsbA-JmWdN4BncHenIG8Wbm3JKzxA1hI4Tg4kwAbhM&m=Fbx0tt6fdV4-rO0MhCvBxeh4m4T1kfzxp6b5GhtScvnj-fMxO1pjweKR1MSAbxz-&s=ME1ZfP4CR0lSoV9uc5XfIyHaMthpVfQwyAVmqDvfOD4&e= . You are receiving this because your review was requested.Message ID: @.***>

[teikmeout]

I agree with what @VickyRampin says. A Jekyll website for documentation seemed a little over-engineered. I'm used to seeing a README.md, and a CONTRIBUTING.md that use Github-flavored-Markdown, that are version controlled with git, that live near the project and can be viewed by everyone since the project is public and all Markdown files render stylized on Github. Having to maintain also a Jekyll site adds the burden of knowing Ruby and Jinja Templates. Dockerizing can be a solution to reduce installation complexity, and that could be the second step on this PR, but still requires things like building and deploying as part of updating documentation. I would rather not need to maintain Ruby gems and just update a Markdown file. I did all this digging to allow the team to make an informed decision. I'm down for whatever direction we want to move. I also don't want to undo someone else's work while not knowing the full intention of having this documentation to be deployed in github pages. Maybe you guys have some better context.

LMK what direction we steer this ship 👍

[teikmeout]

Ok, as we discussed before, I removed Jekyll and Github Pages. This developer documentation is now only Markdown. I recommend we also turn off and remove the Github Action for deploying to Github Pages as well as remove the configuration tying our URL to the site. The rest should be self explanatory: I hope I organized the documentation into something a little more sensical and useful. Please feel free to comment on this PR any other changes you want made to the documentation.

Thank you for your time reviewing this ticket.

[teikmeout]

Nice! thanks for the review and I'll get on to working on your requested changes!

[teikmeout]

OK, changes made. Please go ahead and review your comments and resolve the ones you feel are completed @ekate @lhenze . Thank you again for your time, team!

[teikmeout]

Closing down this PR since it has already been added into the development branch of this project.