improve view-source appearance

[casperdcl]

From https://github.com/NiklasRosenstein/pydoc-markdown/pull/135#issuecomment-660022986

Make [view source] link

• [x] right-aligned
• [x] smaller font
• [ ] on the same visual line as the heading (https://stackoverflow.com/questions/13194692/align-h1-header-and-normal-text-in-same-line)

Even just the first two help, e.g.:

using style="float: right; font-size: 75%;" changes to:

[NiklasRosenstein]

Hey @casperdcl , thanks for the PR. Sounds like a good idea. I'll look to make the actual style of the "view source" configurable, but that doesn't block this PR from being merged.

[casperdcl]

yes and I couldn't find any css files in the repo, which would seem like a good idea for theming...

Ideally everything would then become configurable via css if you start giving things classes/ids.

[NiklasRosenstein]

Actually before merging this I want to check what it looks like when a signature block is rendered, because you moved the render signature call to after the rendering of the [view source] link.

Ideally everything would then become configurable via css if you start giving things classes/ids.

Not sure I'm a big fan of this, it'll eventually end up as an HTML renderer much more than an actual Markdown renderer, which is not the job of Pydoc-Markdown.

[casperdcl]

Actually before merging this I want to check what it looks like when a signature block is rendered, because you moved the render signature call to after the rendering of the [view source] link.

Yes, it looks better this way. See https://tqdm.github.io/docs/tqdm/

Not sure I'm a big fan of this, it'll eventually end up as an HTML renderer much more than an actual Markdown renderer, which is not the job of Pydoc-Markdown.

as a web docs generator, though, I'm not sure if there are better options... Depending on the flavour of markdown, adding metadata such as class/id to elements might be possible using markdown syntax.

[NiklasRosenstein]

I added the customization options I mentioned. The default is still to render after the signature and to use standard Markdown, but you can override it in the MarkdownRenderer settings like so:

renderer:
  type: mkdocs
  markdown:
    source_linker:
      type: github
      repo: tqdm/tqdm
      root: ..
    source_position: before signature
    source_format: |
      <span style="float: right; font-size: 75%;">
      [[view source]]({url})
      </span>

[casperdcl]

Great. Incidentally; is there a way to select the flavour of markdown?

E.g. https://tqdm.github.io/releases/ isn't rendered properly since it uses 2 spaces for list indentation rather than 4.

(I've implemented a work-around for now by indenting list items by 4 spaces)

[NiklasRosenstein]

The markdown flavor depends on the software that renders the markup to HTML. You could adjust the indentation of bullet lists in a pre-processor.

The only part in the MarkdownRenderer that renders a bullet list is the render_toc option. We could probably add an option there to specify the indentation

[casperdcl]

Yes I'm essentially preprocessing. Looks to be more of an upstream issue https://github.com/mkdocs/mkdocs/issues/361