Restructure docs and migrate to Netlify

[stuclem]

Copying the contents of an email thread with @michmike and @xaleeks here:

I propose to divide the content into the following broad sections:

• Harbor Installation, Configuration, and Administration: Install, initial configuration tasks, upgrade/migration, and everything that only the Harbor Admin can do (configuring replication endpoints, project quotas, etc.). Possibly split this into Harbor Installation and Configuration and Harbor Administration. Not sure yet.

  • Comment from @michmike: I like the install, configure/”manage” aspect of the first part. The helm chart needs to be part of this. HA deployment needs to be part of this. I would like a new section on operate. This includes, logging, monitoring, analytics, health API, upgrades, etc.
  • Reply from @stuclem: I think that all of logging, monitoring, analytics, health API, etc. would fall under Administration. Should this be a separate section? I like the idea of separating the day 1 Harbor admin tasks (install, initial config) from the day 2 Harbor admin tasks (managing, administration).

• Working with Harbor Projects: Everything that users with the developer, master and project admin roles can do.

  • Comment from @michmike: I like this. This is all the feature set for all the different roles of harbor
  • Reply from @stuclem: That's my intention, i.e. to cleanly separate the docs for devs/masters/project admins from the docs for the Harbor admins.

• Build, Customize, and Contribute to Harbor: For developers who want to build from source code, customize their deployment, contribute to the project, etc.

  • Comment from @michmike: nice!

Does this organization seem appropriate to you? The monolithic user guide is being broken into chunks and divided between Harbor Installation, Configuration, and Administration and Working with Harbor Projects. The install guide will also be broken up into smaller chunks.

What do you want me to do with the docs that are marked as “by community” on https://goharbor.io/docs/? Should I leave them as they are, or integrate them into the Build, Customize & Contribute docs?

• Comment from @michmike: we can integrate them in the place that makes sense. does that work?
• Reply from @stuclem: Yes

[stuclem]

Wishlist for the new doc site:

1. Publish to https://goharbor.io/.
2. Fully automated build and publication process when doc changes are merged into master.
3. Separate versions of the docs for each x.y version of the product, starting from version 1.10.
4. Versions that pre-date v1.10 to remain in their respective branches.
5. At least temporarily, keep the current .md files in place in the docs folder in master, with their content replaced by a message that this file has moved, pointing to the new location for the doc source files and a link to https://goharbor.io/.
6. Add an Edit this Page button to every page in the output, that when clicked takes you to the source .md file in Github.
7. Even though we are breaking up the big user and installation guides, some topics will still be quite long and will include subsections. Include some kind of in-topic navigation so that users can easily jump to sub-sections within a topic.

@jonasrosland how feasible are the last two items? Thanks!

[jonasrosland]

Item 6 should be pretty easy, by using the variables site.github.repository_url and page.path, I believe. Item 7 is a structure question, if some guides are bigger than others then that's the way it should be :)

[stuclem]

@michmike @xaleeks do we have any existing docs on monitoring, analytics, or the health API? I can't find any in the /docs folder.

[michmike]

LGTM a few notes a. Definitely separate he day 1 Harbor admin tasks (install, initial config) from the day 2 Harbor admin tasks (managing, administration, observability). b. there is very little content here on the health API only...at https://demo.goharbor.io/#/Products/get_health c. we should also add a new section that's around API usage. similar to https://kubernetes.io/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions. we need to include our swagger UI from https://demo.goharbor.io/devcenter as well d. You mentioned a page for the community efforts as well, like the harbor CLI. we need that too.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.