The generated documentation does not integrate into the site

[AlanGriffiths]

The "User manual" and "Developer manual" links go to a section of the site generated from the source code. This is not integrated into the site (different theming, no breadcrumbs, nor links to the homepage).

We should probably integrate the content from these pages...

• Getting and Using Mir
• Getting Involved in Mir

...into the main site and put the remaining generated documentation elsewhere (and link to it).

[frankiegranato]

@AlanGriffiths we are currently trying to figure out ways to do this :-)

[AlanGriffiths]

Let me know if you want help. The (markdown) source of those pages is on github, or I can extract it for you...

[anthonydillon]

Thank you very much Alan. We are currently transiting from documentation-builder to discourse. @nottrobin, could you suggest a plan for this?

As I see it there are two approaches:

1. Move the markdown to discourse and archive the existing GitHub markdown.
2. Pull the GitHub markdown and generate documenting using the old system (documentation-builder)

[Saviq]

There's also the developer documentation (e.g this) that's generated using Doxygen directly from the source code. Today it spits out HTML but using Moxygen we can get markdown out, too - question is whether it's good enough to convert to HTML - I sent an example up to you guys some time ago - let me know if you can't find it.

All the "hand-written" documentation indeed we want to hold on discourse and link to the code-generated as appropriate.

[nottrobin]

I think ultimately all the documentation will be integrated into the site.

Given that the hand-written documentation will move to Discourse, I'd like to propose we wait until we're ready to put it on Discourse (maybe another month or so?) before tackling this documentation. When we've done MAAS and Juju docs, we'll start on this work. Is that okay?

As for the generated documentation, I think that should also be integrated into the site, and we will do that work alongside the Discourse work for hand-written documentation.

I'd like to avoid generating Markdown only to convert it straight to HTML. If Doxygen can generate HTML, we should just make it do that directly in a template format that fits into the site. But anyway, we'll delve into that when we get to the work.

[Saviq]

+1 on all that. I've started writing the docs for Multipass in our discourse.

[tbille]

This is a project in progress for this cycle (20.10) https://github.com/canonical-web-and-design/master-epics/issues/132

[AlanGriffiths]

This is a project in progress for this cycle (20.10) canonical-web-and-design/master-epics#132

Any progress?

[sowasred2012]

@tbille what's the status of this?

[tbille]

@sowasred2012 it seems that this is still relevant. @nottrobin might have more insights about this and the status.

[nottrobin]

There's been no progress on this that I'm aware of. If it was in the plan for 20.10, I don't know what happened to it.

The epic mentioned above only covers adding Discourse-backed docs, which only works for user-written documentation. We would also need to decide how we're handling the documentation that's generated from the code, which would be a separate process - like maybe we get the doxygen system to output template files that we can then plug into our site, or something.

Either way it's going to need to be scheduled in again, unfortunately. @cristinadresch could you maybe see whether we have space?

[Saviq]

FWIW I don't think we should touch this at all without Daniele's involvement.

[anthonydillon]

@evildmp just bumping this onto your radar.

[Saviq]

As I mentioned below, we're working on getting that part of the documentation onto readthedocs, so that should help all this.

#78 (comment)