canonical / documentation-builder Goto Github PK

This issue was forked from #61.

Only including 2nd-level links in the TOC is very limiting, especially for a page such as the release notes. Yet allowing for 3rd-level links brings us back to the issue of duplicate text headers not becoming links. I feel trapped in a small box. Do you have a suggestion as to how the release notes can be displayed? Users complain of not having a decent TOC for such a document. They want to see quickly what new features have appeared and this can be accomplished, in principle, by a TOC, especially since this is what was available in the old MAAS docs.

This MAAS page uses the following code:

[https://images.maas.io/ephemeral-v3/daily/][default-boot-source]
[default-boot-source]: https://images.maas.io/ephemeral-v3/daily/

The point is to have the hyperlink show up as a hyperlink. As is, just the hyperlink text shows up. Trying without the labelling gives the same result.

What I don't understand is why this works on my local web server.

Do we need to highlight to people more clearly when they're on an older version of the documentation?

Numbered lists are reset after each code block:

1. Blah blah blah

1. Blah blah blah

> ```bash
>command1
>```

1. Blah blah blah

I expect
1
2
3

But I get
1
2
1

Currently the docs area occupies all the page. That's not cool. Make it fixed-width like for example the default theme on readthedocs does.

sudo snap install documentation-builder
error: cannot perform the following tasks:

• Download snap "ubuntu-core" (423) from channel "stable" (received an unexpected http response code (500) when trying to download https://068ed04f23.site.internapcdn.net/download-snap/b8X2psL1ryVrPt5WEmpYiqfr5emixTd7_423.snap?t=2016-11-10T00:29:17Z&h=f7331e73d52512cfdc5fe7a6feb433ecd890c903)

As Kyle Nitzsche pointed out, it's not entirely clear that the right hand "table of contents", with the heading "Contents", is in-page links rather than site contents.

We should change the title to "Page sections", or "In this page" or something?

@MonicaSG?

We should implement some tasteful design as a placeholder: at the moment Warnings etc are just styled as plain text.

If a foldout is not followed by another foldout then a blank line should be inserted after it. Otherwise you get text stuck to the foldout when it is folded.

Example #1
> foldout1
[add blank line]
text

Example #2
> foldout1
> foldout2
[add blank line]
text

When building documentation each project requires a number of flags to be set. For example:

documentation-builder --base-directory ../vanilla-brochure-theme/docs \
                      --site-root '/en/vanilla-brochure-theme/index' \
                      --output-path 'en/vanilla-brochure-theme' \
                      --template-path template.html \
                      --tag-manager-code 'GTM-K92JCQ'  \
                      --no-link-extensions \
                      --force

This is difficult to type/remember so the command is normally added to a scirpt like ./build-docs. This makes it difficult to modify the flags like changing the source-directory in a one off case.

I propose that the settings can be stored in a .documentationrc file which is committed to the project and is looked up when running documentation-builder. Therefore you only need to run documentation-builder in the project with overriding flags.

It would be nice/cool if documentation-builder could generate the skeleton files it needs for a repo

I think in 'documentation-builder/ubuntudesign/documentation_builder/resources/template.html'

around line 117 the code should look more like the following:

                {% if item.location %}
                    {% if item.children %}
                    <h4 class="p-sidebar-nav__header {% if item.active %}is-active{% endif %}" href="{{ item.location }}">{{ item.title }}</a></h4>
                    {% else %}
                    <a class="p-sidebar-nav__link {% if item.active %}is-active{% endif %}" href="{{ item.location }}">{{ item.title }}</a>
                    {% endif %}
                {% else %}
                <h4 class="p-sidebar-nav__header">{{ item.title }}</h4>
                {% endif %}

however, I am not sure that 'item.children' is known at the point it is read.

The Doc team needs the ability to remove a deprecated series from the series-selector widget while preserving its content online.

Notes:

• An archive section can be made available in the menu where old series can be stored.
• A deprecated series should have a watermark of sorts that would indicate it is no longer supported.
• It may be possible to include logic, via a combination of a new archived file and documentation-builder, that would avoid uselessly building archived/deprecated series during publication time.

It would be great to have the option ('page_rating_gadget: True') of including a page rating gadget (e.g. click on one of five stars). Here is an example.

We should do the above because a single-page format is a stepping-stone to producing offline docs.

This is possible to do with minimal nonsense from the current metadata.yaml I believe. We would:

1. Get an ordered list of docs by reading the files linked in the navigation
2. Read in the files in sequence
3. remove metadata + insert anchors for the doc names
4. generate one huge string of markdown
5. convert it to html
6. rewrite the internal links to point to the anchors we added
7. dump it in a single file.

This would also require a different template I suggest.

As a proof of concept, I cobbled together something from the Juju docs doing this, then ran it through weasyprint to make a PDF
https://drive.google.com/a/canonical.com/file/d/0B1uxMMubLozZRmh3akF0MjdzeUE/view
Obviously, it needs additional CSS for print, but from a single-page HTML we can also generate other formats very easily.

@yaili requested that we add a burger menu icon to the button which toggles the mobile menu open and closed.

Look into ways of speeding up the builder. Maybe only update if source files are newer?

it is hard to scan for the tab without it.

The breadcrumbs do not correctly align when using Firefox but align correctly in Chrome.

This issue is to track the upstream issue and update here when available.
canonical/vanilla-framework#707

The TOC does not work well. For example, the MAAS docs historical release notes page (source file: release-notes-all.md) exhibits the following symptoms:

• The numerical headers do not produce working TOC entries
• Any identical headers do not produce working TOC entries with the exception of the first occurrence

the docs have javascript too add the class, but the style is missing

At a minimum, it should be possible to determine that any local/relative links are valid and emit warnings if they are malformed

Any markdown files with upper-case names should be ignored, e.g. CHANGELOG.md, README.md.

It would be great to have a "copy" icon appear within a code block when the reader's mouse cursor hovers over it. Here is an example.

The URLize extension applies itself indiscriminately. This means it adds extra markup to existing markup. E.g. in the vanilla-framework docs, outputting broken markup.

URLize should be disabled until this is fixed.

When building docs, we should be able to provide a google analytics code for inclusion in the build HTML.

context.yaml is just cryptic

It would be great to have a plugin that converts text links into true links.

For example:
https://docs.ubuntu.com/maas/devel/en/contributing

Fixes canonical/docs.ubuntu.com#24

See here, and scroll down. The Table of Contents should be sticky, versions should not.

Once the select box styling in docs-vanilla-theme is implemented (in https://github.com/ubuntudesign/docs-vanilla-theme/issues/46):

• Use a select dropdown if there is more than 1 version
• If there is only one version, hide it
• If there is only one version back, use this style: https://cloud.githubusercontent.com/assets/2169216/16558535/453951b4-41de-11e6-8f9e-010012ac59c3.png - using default link style

From 2016-11-08: Docs theme design workshop:

To implement in template.html (mostly JavaScript)

• Say "Back to top" instead of Top in table of contents
  • Only show it when it's relevant
  • Move it bottom of the list
• Make sidenav items collapsable (not just on mobile)
• Small screen:
  • Make breadcrumbs clickable They already are

Following on from canonical-web-and-design/docs-vanilla-theme#4 - instead of making the Table of Contents optional, we should implement a standard rule that it appears when there are X or more sub-headings.

For now I'm going to go with 3 or more. This can be tweaked in the future.

this is making the table of contents bold with a link when NOT active as well as active

The versions file (e.g. in maas-docs) should contain a list of branch names, one per line. The builder should build the documentation for each branch mentioned in the versions file under its own folder corresponding to the branch name. E.g.:

$ cat versions
1.8
1.9
2.0
$ # run the builder
$ tree
.
├── build
│   ├── 1.8
│   │   └── en
│   │       └── index.html
│   ├── 1.9
│   │   └── en
│   │       └── index.html
│   └── 2.0
│       └── en
│           └── index.html
└── versions

However, we have to consider a few user stories here and how best to handle them:

• You have pulled down the repository and you want to build all the documentation exactly as it would be online (including versions)
• You want to build only the current branch - not the version branches
• You have pulled down the master branch as a zip, without the git repository. So there's a versions file but no way to find the version branches

I think either a --versions or --no-versions flag should help with the first two. For the final one, we might need to be a little clever about detecting whether version branches exist, and providing good informative error messages.

context.yaml (which contains, among other things, the navigation) should be able to exist within the language folders so that we can have language-specific navigation.

I think the solution should be that, for building any given page, it looks for a context.yaml in the same directory first, then in the parent directory, etc. up to the root directory. It should do a simple merge (any top-level keys will be replaced), preferring keys from the context.yaml that is closest to the file location.

This will allow you to have a ./context.yaml, which defines site_title, logo_url and a default navigation, and then also have a ./fr/context.yaml which defines a completely different navigation for French pages, but inherits the other settings.

For a page named "content page" on a doc site named "doc site", I would expect the page title to be: "content page", "content page - doc site" or "doc site - content page", but it's always "doc site".

This has a high impact on search results, giving every result the same title: https://docs.ubuntu.com/search?q=image&domain=docs.ubuntu.com%2Fcore

the text should wrap, not the chevron

The Callouts extension was a hack, there is a proper Admonition library. Fortunately, because we already hacked the hack to make it work with the proper syntax, admonitions which follow style will still work with the proper extension.
The new extension does give us finer-grain control over admonitions though.

Currently, if you do documentation-builder in a directory containing documentation markdown files, it will build the HTML files in the same folder next to the markdown files, which is a bit confusing:

$ documentation-builder
Created ./index.html
Created ./somedir/index.html
$ tree
.
├── context.yaml
├── index.html
├── index.md
└── somedir
    ├── index.html
    └── index.md

1 directory, 5 files

It would be neater if we kept this in a build directory of some kind. I propose calling it html. So we instead get:

$ tree
.
├── context.yaml
├── html
│   ├── index.html
│   └── somedir
│       └── index.html
├── index.md
└── somedir
    └── index.md

3 directories, 5 files

Version 1.5.0 installed from pip works fine, but revision 35 of the snap (1.5.0) crashes when fetching version branches of a doc repo.

Trace when used in the run script of https://github.com/canonical-websites/docs.ubuntu.com

david@helena:~/documentation/docs.ubuntu.com$ ./run
yarn install v0.24.4
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
warning Your current version of Yarn is out of date. The latest version is "0.27.5" while you're on "0.24.4".
Done in 20.08s.
yarn run v0.24.4
$ node-sass --include-path node_modules static/sass --output static/css 
Rendering Complete, saving .css file...
Wrote CSS to /home/david/documentation/docs.ubuntu.com/static/css/global.css
Rendering Complete, saving .css file...
Wrote CSS to /home/david/documentation/docs.ubuntu.com/static/css/homepage.css
Wrote 2 CSS files to /home/david/documentation/docs.ubuntu.com/static/css
Done in 0.70s.
Cloning into 'docs/conjure-up'...
remote: Counting objects: 249, done.
remote: Compressing objects: 100% (67/67), done.
remote: Total 249 (delta 28), reused 73 (delta 14), pack-reused 161
Receiving objects: 100% (249/249), 1.31 MiB | 422.00 KiB/s, done.
Resolving deltas: 100% (112/112), done.
Traceback (most recent call last):
  File "/snap/documentation-builder/35/documentation-builder", line 17, in <module>
    cli.main(sys.argv[1:])
  File "/snap/documentation-builder/35/ubuntudesign/documentation_builder/cli.py", line 164, in main
    Builder(**arguments)
  File "/snap/documentation-builder/35/ubuntudesign/documentation_builder/builder.py", line 115, in __init__
    output_path
  File "/snap/documentation-builder/35/ubuntudesign/documentation_builder/operations.py", line 223, in prepare_version_branches
    Repo.clone_from(base_directory, branch_base_directory, branch=name)
  File "/snap/documentation-builder/35/lib/python3.5/site-packages/git/repo/base.py", line 966, in clone_from
    return cls._clone(git, url, to_path, GitCmdObjectDB, progress, **kwargs)
  File "/snap/documentation-builder/35/lib/python3.5/site-packages/git/repo/base.py", line 912, in _clone
    finalize_process(proc, stderr=stderr)
  File "/snap/documentation-builder/35/lib/python3.5/site-packages/git/util.py", line 155, in finalize_process
    proc.wait(**kwargs)
  File "/snap/documentation-builder/35/lib/python3.5/site-packages/git/cmd.py", line 335, in wait
    raise GitCommandError(self.args, status, errstr)
git.exc.GitCommandError: 'git clone --branch=2.1.2 -v docs/conjure-up /home/david/snap/documentation-builder/35/.cache/documentation-builder/tmp8sjzfwox' returned with exit code -31
stderr: 'Cloning into '/home/david/snap/documentation-builder/35/.cache/documentation-builder/tmp8sjzfwox'...
warning: templates not found /share/git-core/templates
done.
fatal: The remote end hung up unexpectedly
'

From @nottrobin on February 3, 2017 8:51

As previously discussed, both MAAS API docs & Landscape API docs are currently created as ReST files. The simplest way to then include these in this site is to parse those files into Markdown and add them to the existing documentation sets.

It would be nice if this could be an entirely scripted task so it's easy to update them as often as we need. A starting point is (from @degville's work):

pandoc --from=rst --to=markdown+backtick_code_blocks+pipe_tables+definition_lists+compact_definition_lists --column=78 --atx-headers --output output.md input.rst

The above command still has the following problems:

• lists are preceded with a redundant '>' because they're indented in
  the original rst document.
• image path needs to be './media'
• most internal references don't work

I also have a worry about doing this, as also articulated on canonical/ubuntu-core-docs#8, that this breaks the purity of the relationship between the built documentation and the markdown repository. This still needs to be discussed further.

Copied from original issue: canonical/docs.ubuntu.com#31