Podman docs

[infiniteregrets]

The present documentation website for Podman is not the best and lacks a lot of UI features that I think should exist, a few examples would be switching between light and dark mode instead of defaulting to browser settings, section on either side of the window that displays available fragments on the page and colored warnings, important messages, bash examples etc.

The website is pretty generic being generated using sphinx (alabaster), and I strongly think that Podman should have a complete new documentation website with a simple but nicer user interface.

A new website can be generated using either of the following options:

• A new theme for sphinx, namely https://github.com/pradyunsg/furo

  Customizable but still does not support switching dark and light modes.

  An example from a community I contribute to:
  https://docs.manim.community/en/stable/reference_index/animations.html

• Vuepress

  https://vuepress.vuejs.org/guide/
  Higly customizable but dark/light mode would need a plugin.

• https://jekyllrb.com/ or https://jaspervdj.be/hakyll/

  Customizable! Good for static sites
  (Hakyll might have a slight learning curve because of Haskell)

• Elm lang

  https://www.elm-spa.dev/guide

  Good for single page applications but requires writing css and scripts to render markdown from a directory.

  https://elm-book-in-elm-book.netlify.app/

  Nice UI but basic layout is not customizable. Still under development.

There are many other ways to generate static sites from markdown and these are the ones that I know about.

If this is something someone is interested in working with me on and is wanted, then we can probably generate a new static website and we can rewrite parts of the documentation following the recently agreed upon manpage syntax while adding examples using https://asciinema.org/ wherever necessary.

I think this project deserves a good and well maintained documentation, so please let me know if this is something we can push forward and get done.

[rhatdan]

Podman is an open source project. We have no Marketing or even Web masters. We rely on community and would love to have the web site updated by people more experienced then the core team. And with more time then us to contribute.

[infiniteregrets]

Okay, I'll see what I can do

[jwhonce]

Any input on podman-py documentation would be great as well. We've been drafting on the podman documentation work.

[infiniteregrets]

I'll be more than happy to work on that, we can probably route them to the main podman docs website. Just it's hard to do stuff alone ):

[infiniteregrets]

Okay so I did some research and got this to work!
This is just a basic layout, I am still working on it. But I was able to embed some asciinemas and I think it would really helpful for users to to have a good walkthrough of various commands.
Here's a few examples. I know a bit of vanilla js and Elm, so I'll explore a few things here and there and see what I can do with react.
I think we can also embed swagger API docs, but I'll look at it later.

[infiniteregrets]

If someone is free over the weekend, can they help me out with this and possibly give me their opinion? If I didn't mention I am using docusaurus

[rhatdan]

I think it looks good. @TomSweeneyRedHat PTAL @jberkus @fatherlinux WDYT?

[fatherlinux]

Yeah, I think this looks great too. I'd be happy to sit down and try and review some ideas synchronously. I made a similar push to update the docs, got one revision done, and lost steam :-) But, I'd probably be a decent person to provide feedback.

[infiniteregrets]

Thank you! Docusaurus is really good for static documentation generation (https://docusaurus.io/) but the react part might be a bit hard for some people, perhaps then I think we could also use mkdocs (https://www.mkdocs.org/). The CirrusCI website is generated using mkdocs for example. (https://cirrus-ci.org/guide/quick-start/)
There are a few more options for which I could show you examples for, and would love to have your feedback but I haven't been able to find any better and easier ones in comparison to the ones I have mentioned.
I am not sure how I can discuss these synchronously and ask my questions, maybe on matrix or irc?

[rhatdan]

I like the looks of cirrus-ci.

[infiniteregrets]

Also, please take a look at these examples here https://docusaurus.io/showcase
We can merge the docs for podman, podman-py and blogs on the same webpage under the navbar.

Kindly let me know, which one you like i.e. mkdocs or docusaurus so that I can work on this

[rhatdan]

I will let @fatherlinux and @TomSweeneyRedHat decide. I like both.

[fatherlinux]

Mehul, I also like the mkdocs site generated for Cirrus CI. I love how fast it is too. If you want to chat more feel free to find me (fatherlinux) on the Kubernetes Slack channel? Or, I'm happy to fire up a web client on the #podman channel on Free Node. I don't always stay connected there, but I could connect. https://slack.k8s.io/ Best Regards Scott M

…

On Thu, Aug 26, 2021 at 9:21 AM Daniel J Walsh ***@***.***> wrote: I will let @fatherlinux <https://github.com/fatherlinux> and @TomSweeneyRedHat <https://github.com/TomSweeneyRedHat> decide. I like both. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#11186 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA4WZLVBMGRDTDWIIOSBA3T6Y5XFANCNFSM5B4OJVNQ> .

-- Scott McCarty ***@***.*** http://crunchtools.com @fatherlinux

[TomSweeneyRedHat]

@baude have you seen this discussion? A possible fix for the podman and podman-py to podman.io discussion.

and shoot, I thought I'd left a reply/comment a while back. @infiniteregrets it LGTM overall, however, I much prefer a white background rather than dark. Could a user toggle that on their own with this, or is that something that would be set once?

[infiniteregrets]

Hi! there will be a toggle button, that's what I wanted in the first place from the current version.
Scott mentioned that it would be a long process to get this stuff merged, would really appreciate if someone guide me how to approach this once I hear back from Scott and what he suggests