Reorganize documentation #1812

carolynvs · 2021-11-01T23:13:45Z

What does this change

Add operator docs from the operator repo to the porter website. The magefile handles cloning the repo, or using a local copy based on the PORTER_OPERATOR_REPOSITORY environment variable.
Update our navigation based on our new design at https://hackmd.io/roa3Nfh4SruG0FFKyJwb7Q. This is a work in progress but all of the top level nav links are now organized according to that document. Further work is needed to edit existing pages in cases where we have combined tasked based docs with references, etc.
Edited some of the docs pages to work with the new navigation.
Updated our CSS so that the left hand nav can show 3 levels of links. Long term, we should look at how the docsy theme does navigation as what we have is difficult to work with.

Preview of operator docs at https://deploy-preview-1812--porter.netlify.app/operator/
Preview of v1 installation docs at https://deploy-preview-1812--porter.netlify.app/install/#v1-prerelease

What issue does it fix

Closes #1807
Closes #1513
Part of getporter/operator#45, additional changes to the operator repo are still required after this is merged.

Notes for the reviewer

None

Checklist

Unit Tests
Documentation
Schema (porter.yaml)

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

The left nav previously was hard coded to only display 2 levels of docs. As a short term fix to support additional levels, I've added tweaks so that we can show links 3 deep. Long term we should use a menu system like what the docsy theme uses for more flexible menus. Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

Our current structure is difficult to add new content to without forever making the number of nav groups increase over time. This reorganizes our navigation according to the new design which categorizes pages by their type (concept, task, reference) and the intended audience (end-user, admin, author, developer). Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

Some pages had TODOs, or the pages they linked to weren't correct after reorganizing the nav bar. I've updated pages to improve the navigation. Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

iennae · 2021-11-04T04:52:31Z

any chance of labeling the Porter Operator with some kind of "in development" label for the page? Also feels like a link to provide feedback on the operator somewhere.

iennae · 2021-11-04T05:02:58Z

docs/content/author-bundles.md

-* exec - run shell scripts and commands
-* helm - use the helm cli
-* azure - provision services on the Azure cloud
+There are [many mixins](/mixins/) created both by the Porter Authors and the community.


nit: Porter authors are part of the community. Are some mixins considered "official" Porter author maintained? or are they all community driven?

Some mixins are maintained by the Porter project, i.e. they live in our github org (getporter). Others are maintained by a community member on their own and we aren't involved. I wasn't sure how to say that well.

does it need to be separate? because it's possible that mixins would be adopted to the official organization?

iennae · 2021-11-04T05:04:49Z

docs/content/install.md

@@ -10,6 +10,7 @@ We have a few release types available for you to use:

 * [Latest](#latest)
 * [Canary](#canary)
+* [v1 Prerelease](#v1-prerelease)


nit: what if this was just prerelease, and then within the "Prelease link it talked about v1 specifically?

I like it, thanks!

iennae · 2021-11-04T05:05:38Z

docs/content/install.md

+# v1 Prerelease
+
+We would love for you to try out v1 prelease and send us any feedback that you have!
+Keep in mind that the v1 prerelease is not suitable for running with production workloads, and that data migrations will not be provided or supported for v1 prerelease.


"Keep in mind that prereleases are not suitable for production workloads. Data migrations will not be provided or supported for prereleases."

iennae · 2021-11-04T05:06:34Z

docs/content/install.md

+
+We would love for you to try out v1 prelease and send us any feedback that you have!
+Keep in mind that the v1 prerelease is not suitable for running with production workloads, and that data migrations will not be provided or supported for v1 prerelease.
+The prerelease is intended for you to try out the new features in Porter and provide feedback. It won't work with existing installations.


Prereleases are intended for you to try out potential new features in Porter and provide feedback about the direction of the feature. They won't work with existing installations.

iennae · 2021-11-04T05:09:11Z

docs/content/install.md

+Keep in mind that the v1 prerelease is not suitable for running with production workloads, and that data migrations will not be provided or supported for v1 prerelease.
+The prerelease is intended for you to try out the new features in Porter and provide feedback. It won't work with existing installations.
+
+One way to try out Porter without messing with your current installation of Porter is to install Porter into a different PORTER_HOME directory.


You can try out different versions of Porter without impacting your current version of Porter by installing to a different location via a modified PORTER_HOME environment variable.

iennae · 2021-11-04T05:11:08Z

docs/content/install.md

+```
+
+Now when you want to use the v1 version of Porter, set the PORTER_HOME environment variable and add it to your PATH.
+


I'm confused by the setting of environment variables (other than for the Windows instructions). Is there a missing step or is it assumed that they are in the right directory to start with?

Thanks for calling that it, I see now that I left off how to use porter after installing, i.e. how to reset the env vars each time you want to switch to a different version of porter.

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

carolynvs · 2021-11-05T21:33:15Z

@iennae Please take another look!

iennae · 2021-11-11T05:28:46Z

docs/content/author-bundles.md

-* exec - run shell scripts and commands
-* helm - use the helm cli
-* azure - provision services on the Azure cloud
+There are [many mixins](/mixins/) created the Porter community.


ahh missing the by the Porter community here.

iennae

overall other than the missing by LGTM

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

carolynvs added 4 commits November 1, 2021 18:17

Add operator to Porter docs

22d6267

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

Update pages to match new navigation

3410a89

Some pages had TODOs, or the pages they linked to weren't correct after reorganizing the nav bar. I've updated pages to improve the navigation. Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

carolynvs force-pushed the operator-docs branch from 7025008 to 3410a89 Compare November 1, 2021 23:51

carolynvs added 3 commits November 1, 2021 19:07

maybe?

7dd8876

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

Debug

0b6f304

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

Fix linking to the operator source docs

89e4e8e

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

carolynvs marked this pull request as ready for review November 3, 2021 15:30

carolynvs requested review from jeremyrickard and vdice as code owners November 3, 2021 15:30

carolynvs requested a review from iennae November 3, 2021 15:32

iennae reviewed Nov 4, 2021

View reviewed changes

Review feedback

eeebe8d

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

carolynvs force-pushed the operator-docs branch from 5fb407c to eeebe8d Compare November 5, 2021 21:32

iennae reviewed Nov 11, 2021

View reviewed changes

iennae approved these changes Nov 11, 2021

View reviewed changes

Fix typo

f35cc08

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

carolynvs merged commit ca49edf into getporter:release/v1 Nov 13, 2021

carolynvs deleted the operator-docs branch November 13, 2021 14:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorganize documentation #1812

Reorganize documentation #1812

carolynvs commented Nov 1, 2021 •

edited

Loading

iennae commented Nov 4, 2021 •

edited

Loading

iennae Nov 4, 2021

carolynvs Nov 4, 2021

iennae Nov 11, 2021

iennae Nov 4, 2021

carolynvs Nov 5, 2021

iennae Nov 4, 2021

iennae Nov 4, 2021

iennae Nov 4, 2021

iennae Nov 4, 2021

carolynvs Nov 5, 2021

carolynvs commented Nov 5, 2021

iennae Nov 11, 2021

iennae left a comment

		```

		Now when you want to use the v1 version of Porter, set the PORTER_HOME environment variable and add it to your PATH.

Reorganize documentation #1812

Reorganize documentation #1812

Conversation

carolynvs commented Nov 1, 2021 • edited Loading

What does this change

What issue does it fix

Notes for the reviewer

Checklist

iennae commented Nov 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs commented Nov 5, 2021

Choose a reason for hiding this comment

iennae left a comment

Choose a reason for hiding this comment

carolynvs commented Nov 1, 2021 •

edited

Loading

iennae commented Nov 4, 2021 •

edited

Loading