New web stack POC

[agardnerIT]

Hi all,

I spent some time translating the docs to mkdocs.

This now runs easily with mkdocs serve.

It can be build with mkdocs build

It can be auto-deployed to GitHub pages with mkdocs gh-deploy

As I've stated elsewhere, I'm happy to help maintain the docs.

What are the projects thoughts on moving to this as it seems much more maintainable.

[AntoineThebaud]

That looks great! Personally the 2 main issues I have with the current doc is:

• Not enough nesting allowed Fix broken DaC doc structure #23
• Pages within a same section are ordered by their title alphabetically, which is too restrictive (you may want to have an "Introduction" coming first then a "Conclusion" for instance :D)

I dont know much the current framework though, maybe these could be solved somehow.. but by any chance does your mkdocs-based website solve these 2 problems?

Could you share more screenshots of the different sections?

[agardnerIT]

1. Yes, nesting is arbitrary.
2. Yes, ordering is set by you in nav of mkdocs.yml

The nav section of mkdocs.yaml

nav:
  - 'Home': 'index.md'
  - 'Docs':
      - 'docs/index.md'
      - 'Authentication': 'docs/authentication.md'
      - 'DAC':
        - 'X': 'docs/dac/something.md'
        - 'Page One': 'docs/dac/index.md'
  - 'Demo': 'https://demo.perses.dev'

[AntoineThebaud]

Great! Btw does it support switching Perses versions easily like we have currently?

[Nexucis]

It can be auto-deployed to GitHub pages with mkdocs gh-deploy

For the moment the website is served on a VM behind a reverse proxy (traefik) that helps to ensure we have a proper certificat for the DNS perses.dev.

Will it be possible to keep this way ?

[Nexucis]

Are you able to support the mermaid schema ? Just to know if it will help to fix the current issue #30

[Nexucis]

Great! Btw does it support switching Perses versions easily like we have currently?

would be so cool to be able to fix #13 with this change

[agardnerIT]

Versioning

Yes: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning

See here: https://agardnerit.github.io/persesdocpoc

Check the gh-pages branch of this repo. Each docset is pushed to a dedicated folder. index.html does the redirect and versions.json is the reference list.

The commands are:

mike deploy 0.2 --push
# When ready to make 0.2 the "latest" version
mike set-default 0.2 --push

Serving

Yes. mkdocs build ultimately translates HTML + markdown to static files.

You can host those static files however / wherever you like. FWIW Github pages allows setting a custom domain so that could be an option should you wish to retire that VM.

Diagrams

Yes: https://squidfunk.github.io/mkdocs-material/reference/diagrams/

[Nexucis]

Awesome, that sounds good for me.
Thank you for answering all the questions we have !

@AntoineThebaud @nicolastakashi are you also to move forward on this and migrate to mkdocs ?

[nicolastakashi]

Hey!
@agardnerIT thanks for handling that.
I've been thinking about the same thing, especially after spend a lot of time upgrading template and not having any success, customization on docs is being very trick, we've been using it in Prometheus Operator but the template is not very flexible.

I'm good for this adoption, especially because mdoks using material theme is a very nice experience, I'm using it internally on my company to another matters.

I'd love to know how I can support with on this journey.

[Nexucis]

great ! thank you for your quick response @nicolastakashi !

@agardnerIT please let us know how we can help you to make this migration, and thank you for proposing it ! 🙏

[agardnerIT]

I’ll start working on this. Should we lift and shift the docs “as-is” or take the opportunity to “split” the user journey path into two sides:

1. Perses the dashboard spec path
2. Perses “the tool”

1 would cater towards other vendors and those who wish to support the DAC spec (import Perses config and translate to vendor, support exporting to Perses format etc.)

2 would cater for those who wish to use Perses as a product

[Nexucis]

I would start to migrate as is.

In the meantime, I would be curious about what do you have in mind exactly when you are talking about splitting.

I'm curious, because for the moment, the dashboard spec is quite clear from my perspective as it is described in the API specification.
But as I have literally written it, I don't have a fair point of view :)

[Nexucis]

By the way, when performing the changes, could you also add the Linux Foundation footer please ? This is part of the cncf/sandbox#134 tasks:

Ensure LF footer is on your website and guidelines are followed (if your project doesn't have a dedicated website, please adopt those guidelines for the README file).

Would be cool if it's possible to have it !

[nicolastakashi]

I agree with @Nexucis about this as is change.
Regarding docs rebrand if you want we can talk to our website mantainer on the prometheus operator, he did a very nice job and maybe might have some experience to share.

[Nexucis]

Also in my Christmas list, it will be interesting to have a place for blog post or at least be able to reference external blog post. 👼

We could start by this one: https://horovits.medium.com/unveiling-perses-the-gitops-friendly-metrics-visualization-tool-f05b5324d7da.

I think Dotan makes a great introduction about Perses :)

[agardnerIT]

Thanks all. I'm arranging KCD Sydney this week but I'll get on this next week.

The material theme does indeed look like they have blog capabilities but for speed, I'll add a "Resources" page where we can (to start) just link out to external content.

I'll lift and shift as-is for speed + add the LF banner.

[Nexucis]

Thanks to @agardnerIT we have a beginning of a new website stack (see cncf/toc#35).

Before removing the previous website, I would like to see the versioning working. I didn't take that much time to understand how it is supposed to work, specially since the doc is outside of this repository.

In the meantime @agardnerIT you had some ideas to rework the website. Would you mind to share what you have in mind ? Would be interesting to rework this website :). Specially the home page. I think home page and introduction could be merged. (and also updated. Because the introduction is still saying we are part of the cordash community which is not the case anymore)

[Nexucis]

Also homepage need to be updated anyway because we have to say we are part of the CNCF and showing the logo (as required by CNCF)

[Nexucis]

After spending some time playing with the versioning, my conclusion is: it's not compatible with the multi repo documentation.
That's unfortunate.

[agardnerIT]

@agardnerIT you had some ideas to rework the website

My opinion is that there are a few personas who would be interested in Perses:

1. Someone wanting to use Perses as a product
2. Someone wanting to build compatibility with Perses (think other projects or Vendors who offer UIs and want to interop with Perses).

For the first set of people, they'd want to know all about Perses as a standalone product. The dashboard, how to create projects, dashboards and how to get data into / or otherwise visualise their data using PErses. They would also want to know how to spin up, host, maintain, secure and monitor a Perses instance / cluster.

Firs the second set, they'd be more interested in seeing how "their stuff" could co-exist / be replaced by / migrate to or translate into or out of Perses format.

[agardnerIT]

After spending some time playing with the versioning, my conclusion is: it's not compatible with the multi repo documentation.

At the end of the day, mkdocs gh-deploy just generates a bunch of static HTML files and pushes them to a branch gh-pages.

It would take a little bit of tweaking the template but I can imagine that anything commits to main trigger an auto build and push to the root of gh-pages. Thus main is always effectively latest.

Then a Github action that responds to new Git tags being created. So I create a v2 tag which builds and pushes to gh-pages and creates a v2 docs folder. Then we find a way (perhaps custom dropdown?) to link to https://perses.dev/v2 which contains the docs at that tag.

Yes, the "OOTB" mike tool may not work, but it's still feasible.

[Nexucis]

sorry for the long time to reply @agardnerIT !

Perhaps for the multi repo / multi versionning issue, we could have the perses documentation on perses.dev and then later the perses-operator on anothre sub domain, like operator.perses.dev for example. Same for helm if we need a doc at some point helm.perses.dev

That would solve the multi-versionning + multi repo issue at the same time in a simple way (with no weird script).

Regarding your opinion about how the doc should guide the user, it looks really interesting, I am looking forward to see the improvement you want to make if you still want to do it of course.

[Nexucis]

The new website is finally deployed. Thank you to everyone that made that possible.

I am closing this issue as it was about the new stack which is used now. For design or others questions, it should go in another issue if there is still an interest.