New self-hosted documentation site

Hey,

We’re looking at moving away from readthedocs.io for the LXD documentation, instead self-hosting it directly on our website.

A first attempt at that can be found here: https://linuxcontainers.org/lxd/docs/master/

The source data/content is identical to what’s on read-the-docs, but we’ve had the documentation generator tool do a bit more work to group topics together.

Let me know what you think and if there’s any obvious rendering/linking issues you can find.

The next step for us will be to land the same structure metadata in the 2.0 and 3.0 branches so we can have the documentation for all 3 branches (2.0, 3.0 and master) available on our website. Once that’s done, we’ll be at parity with readthedocs and will replace the various links.

4 Likes

I like it! Seems easy to read.

One suggestion - add the current version string (ie v3.16) of LXC/LXD somewhere at the top of the Getting Started page. Either put it in the first paragraph or in the table. It would be nice to see the current version ID with a link to the current changes plus the upcoming version with it’s list of changes.

My $0.02

On the plus side:

On the minus side:

  • no search (or should it be: NO SEARCH ??? AARGH !)
  • when selecting an item on the left side, the whole screen is redrawn, if the selected item is not displayed on the screen (because it’s at the bottom of the left side that’s too big for the screen height) it’s not shown anymore
  • some items on the left side are cut too short in my browser (Frequently Asked is displayed instead of Frequently Asked Questions for the ReadTheDocs version)
  • less readable (I guess that’s a personal point of view then, but IMO titles in bold make a long page more readable, it’s faster to zero in on what one is searching for)

Neutral: replacement of the accordion design by another menu to the right to navigate the loaded page. Pity that using it scrolls the left hand menu too.

On balance, the ‘no search’ point is just dreadful. I don’t expect my point of view to matter in any way :slight_smile:

I’ll have to do what we can do for search, I think there’s something I can set in documentation-builder to integrate some kind of google search. Since all the content is static, we can’t really do any fancy indexing/search on our side, but if we can delegate to Google, that should be fine.

For Frequently asked, it’s the actual title for that menu entry. One thing the new tool lets us do is decouple the entry name on the left side to the page title, letting us use shorter entries to avoid wasting screen space.

The redraw is somewhat expected as we each page is statically generated and completely independent from the others. That’s great to be able to download/save/export, but does come with the downside that you get a full page redraw every time.

I would like the left navigation bar to be independent from the rest of the content, so that it and the title (with the LXD logo) can stay on screen at all times, but that may be more CSS magic than I’m capable of :slight_smile:
If someone can figure out what change to do to the CSS to have it behave that way, let me know and I’ll update the template.

I’ll take a look at the difference in title rendering, changing that is definitely within my CSS skills :slight_smile:

A small thing, I noticed the links to sub-sections don’t appear to be working e.g.

https://linuxcontainers.org/lxd/docs/master/containers#device-types

There’s a link to “nic” device type, which appears as a link but doesn’t go anywhere.

https://linuxcontainers.org/lxd/docs/master/containers#type-nic

Which tool you use for build documentation (Linux Containers - LXD - Has been moved to Canonical)?

documentation-builder

Are you sure of that ? Everytime i have tried to search for something like
site:mysite.org/mysubdir
on a search engine, the darn thing returned everything under mysite.org, including subsites like for example community.mysite.org.

When you are searching for up to date documentation, the last thing you want is a selection of forum posts based on their popularity, with the flamewar of 2 years ago, the update troubles of last year appearing far higher ranked than current doc, while talking about obsolete problems.

But I think that if you used docs.linuxcontainers.org instead of linuxcontainers.org/docs, standard search engines would do much better. Your index could be just a quick note: for searching use site:doc.linuxcontainers.org in your favourite search engine.

Search is a bust so far, getting this working well with the tool is a PITA and I’m not sure how much time I’m willing to put into it.

I did manage to get the titles to be bold and to better scale too, so that worked at least.

Taking a look at the linking issues now, not sure what’s the best way to sort those out yet.

Ok, so that’s because the title is actually type: nic so that became #type:-nic rather than #type-nic.
I need to find some clever way to have the jinja2 template do that rewriting.

Looks like its working now, thanks.

Yeah, I’ve altered the python plugin which was used to generate those and had it strip colons.