[Proposal] - Create standard python documentation site for Pulumi SDK

[komalali]

Related to: https://github.com/pulumi/docs/issues/4615

Our current python SDK documentation page is difficult to navigate and has a number of formatting errors (as described in #4615). This is a proposal to lift and shift our python documentation to us the standard readthedocs theme, implement navigation, improve formatting and move to a structure that python users are familiar with.

An outline of the steps required to enable this:

• [ ] Build a standard doc site with Sphinx: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
• [ ] Modify the generated sphinx files (use the existing pulumi.rst file and typescript docs as templates for what information to include)
• [ ] Deploy the documentation as part of pulumi.com.
• [ ] Update any links that might require updating

Notes: When picking up this work, sync with @susanev on bringing in the practitioner nav

[komalali]

Following up to add some more color/clarity because I know there are some concerns here.

Concerns I have heard:

1. Losing design/style consistency with other language SDKs
2. We need to host this as part of pulumi.com

Current state

Our Go SDK docs are on pkg.go.dev so they are neither in pulumi style or hosted on pulumi.com. Our Dotnet SDK docs also follow dotnet-specific styling, so they are not in pulumi style (but they are hosted on pulumi.com). Realistically, there is no shared style between the 4 SDKs as even Nodejs and Python are different from each other.

Below is a screenshot of the current layout. It is not easy to discern that apply is a method on Output. Things like __getitem__ should not be included in this page. I could pinpoint every single issue in this image but I think it is clear that it is not "easy" to understand.

Updated proposal

I have updated the description above to concretely state that we will host these docs on pulumi.com whether or not we choose to use the readthedocs theme.

As for the styling, that is TBD. My primary concern is that we have a usable, navigable documentation page for the python SDK. One that has functional navigation (and potentially separate sub-pages for things like automation API). We could continue to work within the framework that exists, or we could adopt the readthedocs theme (but only because of the built-in processing of rst documents).

[komalali]

A summary of the proposed changes condensed by @susanev after chatting with @infin8x

• still be able to navigate to the python api docs from pulumi.com/docs but it will take you to a page within pulumi.com that's on its own not within the docs constructs
• will use a readthedocs theme, and possibly make a few small style adjustments if its easy and makes sense
• will add the practitioner nav to the top of this experience so its easy to get back to the pulumi.com/docs or other marketing content
• will get a nav on the page to make it easy to navigate these python docs
• will improve the general content and structure of the information

[infin8x]

Yep, this all sounds great - thanks @komalali! To zoom out a bit from the proposal, some guiding principles I'd propose (that the proposal above aligns with):

• The Python docs should feel great and feel familiar to experienced Python users. For example, as a Go user, I know exactly how to interact with our Go docs because there's a standard format with standard interaction patterns.
  • A sub-point of this is that I would prioritize feeling familiar to the Python ecosystem over feeling 100% stylistically consistent with our Docs and our general look-and-feel
• If we end up not using the Docs navigation, there does need to be an easy way to understand where you are and how to get back to the Docs, if you came from there