docs icon indicating copy to clipboard operation
docs copied to clipboard

Published 20 hours ago • verified publisher icon pulumi

Sphinx-generated Python Docs Issues

Open lukehoban opened this issue 5 years ago • 4 comments

The doc-generator we use for Python-specific API docs, and in particular https://www.pulumi.com/docs/reference/pkg/python/pulumi/, has many issues. We may need to wholesale replace the technology we use for generating these docs to ensure higher quality.

  • [ ] https://github.com/pulumi/docs/issues/906
  • [x] https://github.com/pulumi/docs/issues/1623
  • [x] https://github.com/pulumi/docs/issues/3332
  • [x] https://github.com/pulumi/docs/issues/3717
  • [x] https://github.com/pulumi/docs/issues/4052
  • [ ] https://github.com/pulumi/docs/issues/1595
  • [ ] https://github.com/pulumi/pulumi-hugo/issues/434
  • [ ] https://github.com/pulumi/docs/issues/7000
  • [ ] https://github.com/pulumi/docs/issues/6426

Some of these may be partly addressed by https://github.com/pulumi/docs/issues/4071, but we will still have some SDKs like https://www.pulumi.com/docs/reference/pkg/python/pulumi/ that need vanilla Python docs.

lukehoban avatar Nov 17 '20 21:11 lukehoban

We (@davidwrede, @infin8x and I) recently chatted about this when it came up w.r.t Automation API docs. I'd suggest using the default or Read the Docs theme and just going with the sphinx autogeneration rather than trying to fit this into our markdown format.

komalali avatar Jan 25 '21 17:01 komalali

I went through the linked issues and noted which ones I expect to be resolved by pulumi/docs#4071

komalali avatar Jan 26 '21 20:01 komalali

+1 for this. For the Automation API I find Pulumi's native go docs way easier to navigate than an unindexed single page for python which is almost unusable in it's current state. See formatting here for example: Screen Shot 2021-04-22 at 7 47 07 am

followben avatar Apr 21 '21 23:04 followben

+1 for this. For the Automation API I find Pulumi's native go docs way easier to navigate than an unindexed single page for python which is almost unusable in it's current state. See formatting here for example: Screen Shot 2021-04-22 at 7 47 07 am

Indeed. There's tons of this bad formatting (we call it "formatting", but really, information is lost!) everywhere in the doc

jf avatar Jul 13 '22 12:07 jf

I have a WIP branch that switches over to using vanilla sphinx: https://github.com/pulumi/docs/compare/master...justin/python. I think all that's left is rebasing that branch and regenerating, then then opening a PR to get feedback.

Going to try to get this over the line next week as one of my hackathon projects.

justinvp avatar Nov 02 '23 23:11 justinvp