Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure docs folder and website for usability and clarity #4430

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

dtzhou2
Copy link
Contributor

@dtzhou2 dtzhou2 commented Jun 9, 2024

What this PR does and why is it needed

  1. Clean up old/unused files in docs/installation
  2. Add in files that werent referenced by mkdocs but considered relevant documentation
  3. Delete unused and irrelevant documentation (running_rpm.md)
  4. Move items in the website around for clarity (Introduction/introduction served the same purpose as getting started/introduction so I combined those sections and moved launching-ovn-kube-on-kind into the getting started folder since it seemed more relevant there)

Which issue(s) this PR fixes

Fixes #

Special notes for reviewers

Changed index.md to README.md. Tested with mkdocs and apparently using index.md instead of README.md means it will not properly be in a subheading in the website columns. Using README.md is workaround for that problem

How to verify it

Details to documentation updates

Instead of changing documentation mostly making sure documentation more accessible.

Description for the changelog

Refactored docs folder structure

Does this PR introduce a user-facing change?


Signed-off-by: Daniel Tianqi Zhou <dzhou@redhat.com>
@dtzhou2 dtzhou2 requested a review from a team as a code owner June 9, 2024 03:12
@github-actions github-actions bot added the kind/documentation All issues related to documentation label Jun 9, 2024
@coveralls
Copy link

Coverage Status

coverage: 52.728% (+0.03%) from 52.702%
when pulling 8c571d0 on dtzhou2:doc_rearrangement
into bf06da7 on ovn-org:master.

@@ -64,7 +64,16 @@ markdown_extensions:
- toc:
permalink: true
nav:
- Introduction: index.md
- Getting Started:
- Introduction: README.md
Copy link
Member

@tssurya tssurya Jun 10, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hold this change, its conflicting with https://github.com/ovn-org/ovn-kubernetes/pull/4333/files#diff-98d0f806abc9af24e6a7c545d3d77e8f9ad57643e27211d7a7b896113e420ed2 why is the index.md file getting removed like that? IMHO its better to remove the introduction bit from getting started..

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I renamed index.md to README.md so we could both include it in the nav bar and use it as the homepage

- Setup and Building: getting-started/building-ovn-kubernetes.md
- Run OVN-Kubernetes From Release Image: getting-started/running-release.md
- CLI Guide: getting-started/cli-guide.md
- Configuration Guide: getting-started/configuration.md
- Overview:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overview should be first, not sure why Getting started is moving positions here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had getting started in the first position because it contained the index/homepage for the project since I deleted the introduction subheading.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, I don't think we need overview in getting started so we can keep things where they are in that case at least that's the change I had proposed in my PR for the release cut, but ofc I don't have strong opinions either ways.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I felt that it was better for UI simplification since right now the index page gets its own subheading, which seems a little wasteful. Maybe instead we can just remove the subheading and keep everything else where it is?

Copy link
Member

@tssurya tssurya Jun 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah that's the bit I did in my PR PTAL, if you rebase this we can have another round of reviews
the other thing I was thinking is.. is there any use to keep the deprecated docs at all? (thinking out loud here.. will ask team for second opinion on if we should probably just get rid of these ...)

Copy link

This PR is stale because it has been open 90 days with no activity. Remove stale label or comment or reach out to maintainers for code reviews or consider closing this if you do not plan to work on it.

@github-actions github-actions bot added the lifecycle/stale All issues (> 60 days) and PRs (>90 days) with no activity. label Sep 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind/documentation All issues related to documentation lifecycle/stale All issues (> 60 days) and PRs (>90 days) with no activity.
Projects
Status: Todo
Development

Successfully merging this pull request may close these issues.

3 participants