feat: user documentation directly in the application

[TheauW]

No description provided.

[aldbr]

I wonder if it wouldn't be better to manage the documentation from a single source, namely /docs/, where we also host the dev and admin documentation. I have the feeling it would be easier to maintain.

But then, the questions is: should we deploy the user documentation both in readthedocs and the web interface? Or should we completely separate it from the other documentations when we deploy them? Then it means we would deploy the admin and dev documentation in readthedocs and the user documentation would go here (e.g. fetching the github raw content).

Of course the simplest solution would be to have everything in /docs... which means we stop going in that direction (at least for now).

We can discuss about that tomorrow, but I think for now I would:

• add your documentation about the SearchBar in /docs/users in the other PR
• and we just stop the development of this solution for now (and revisit it if needs be in the future)

Do you have any opinion?
Sorry...

[aldbr]

What could be potentially interesting is a guided tour (e.g. https://www.shepherdjs.dev). I don't think it's the priority though.

[fstagni]

I think the user documentation can stay here, and the admin and dev in rtd. We can anyway decide f2f.

[aldbr]

I see 2 potential "problems" with the approach:

• a significant amount of manual work: extensions seem to need to embed a generatedDoc.ts script
• the documentation is "duplicated" within the source code

I have the feeling this is a common problem, but we have the extra complexity of supporting extensions.

What about:

• you export /docs/users when you build diracx-web-components: may be just by copying *.md files into *.mdx
• in diracx-web and gubbins you leverage the NextJS config to get the *.mdx content and incorporate it into the help component.

Here are a few resources that might help:

• https://mdxjs.com
• https://nextjs.org/docs/pages/guides/mdx
• https://contentlayer.dev
• https://contentlayer.dev/examples/nextjs

Have you already explored MDX and its integration with NextJS?
I don't know exactly how to connect the pieces and whether it's feasible, but I have the feeling it could potentially prevent us from doing too much manual work and "duplicate" the documentation.

If not already done, could you have a look please?