Mercurial docs improvements?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Mercurial docs improvements?

Ludovic Chabant
Hi there!

I started playing around with improving the Mercurial docs but before I
work on it more and send some patches, I wanted to get some opinions
about what people would like to see here. Sorry about the length of this
email but there's a lot to do IMHO.

What I have in mind is the following grand plan (I don't know if I'll
get to do everything but this is what I would _like_ to happen):

1. Make doc/Makefile also generate one html and man page per command and
   extension.

- This would let us see the doc for, say, `hg status` over at
  https://www.mercurial-scm.org/doc/hg-status.1.html
- When you just want to check the docs for a single command, it's a lot
  easier than having to search "status" (with multiple hits) on the
  giant hg.1.html page (I know I could just check the doc in my
  terminal but sometimes I can't, or I prefer the browser for one
  reason or another)
- It would generate `hg-<cmd>.1` pages (note the .1 suffix) because we
  have this 1:1 mapping between man pages and html pages -- I assume we
  want to keep that.
- This would also give us the ability to type, say, `man hg-status` and
  get a man-formatted version of `hg help status`. I don't care too much
  for that but I suppose it doesn't hurt.

2. Improve integration of generated docs inside the website

- Change the html template used to generate the html docs so that it has
  the standard website navigation around the content.
- Right now that's the top horizontal menu, more or less (but that might
  change, see next points).
- If people prefer the online docs to not have this, we could generate 2
  versions of the html: the `<whatever>.1.html` would be the "naked" man-
  like doc in html form, while the `<whatever>.html` (without the man-
  like number suffix) would be the "website integrated form"... or maybe
  not and we just force people to hit the Back button often.
- Generate some doc index page with links to all the other generated
  pages (categorized links to each command page, general links to
  hgignore/hgrc, extensions, etc.)

3. Improve the website itself

- Adding some proper link to the reference documentation (i.e. the
  generated html doc pages... note how my previous point mentions
  generating an index page for those, so that's what we would link to)
- Take a hard look at the navigation. Right now we have only a top
  horizontal menu, which means only a handful of menu items at most.
  This means that a lot of the navigation should be done with clear
  lists of subpages on each top level page, so that it's easy to get a
  mental picture of the website's structure, but in practice the links
  are placed organically in the text and I find that confusing. It's
  especially confusing when you have somewhat duplicate things (a
  "Quickstart" sidebar on the main page, but also a dedicated
  "quickstart" page), links to take you out to the wiki, interesting
  pages whose links are buried in the text ("learn" page), etc.
- There should be a "Release Notes" or "What's New" link on the website
  (I couldn't find one?), shown prominently on the "Downloads" page, and
  that should link to a "proper" website page, too (possibly generated
  like the reference docs), instead of linking to the wiki (but that
  depends on how much manual labour goes into publishing the release
  notes, I'm not familiar with that process).
- Similarly, I think the "Extensions" page on the website should be a
  "proper" website page, at least as far as general docs and bundled
  extensions go. It could link to the wiki for 3rd party extensions.
  Honestly, it could (should?) be a link to the `hg help extensions`
  topic as generated in html form, with some added bells and whistles
  like links to each extension's reference doc page.
- Add some "Get Involved" page (couldn't find any either?) for how to
  ask for help, report bugs, and contribute patches.

4. Make reference docs versioned

- The reference docs (hg.1.html, hg-status.1.html, hgignore.5.html,
  etc.) should be versioned, so you can check out the docs from a
  prior version of Mercurial (which is particularly helpful when
  helping someone).


Phew, I think that's it!   Right now, I've got #1 mostly figured out and
done, and I started playing around with #2.

Comments?

--
 l u d o .
 . 8 0 17 80
_______________________________________________
Mercurial-devel mailing list
[hidden email]
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
Reply | Threaded
Open this post in threaded view
|

Re: Mercurial docs improvements?

Jordi Gutiérrez Hermoso
On Mon, 2019-02-18 at 12:48 -0500, Ludovic Chabant wrote:
>
> 1. Make doc/Makefile also generate one html and man page per command and
>    extension.
>
> - This would let us see the doc for, say, `hg status` over at
>   https://www.mercurial-scm.org/doc/hg-status.1.html

As we discussed in IRC, that page already exists, but it's hard to
find:

https://www.mercurial-scm.org/repo/hg/help/status

> 2. Improve integration of generated docs inside the website
>
> - Change the html template used to generate the html docs so that it has
>   the standard website navigation around the content.

We can make the hgweb installation at mercurial-scm.org use whatever
template we want. It makes sense to me to give it a template that
matches the non-hgweb part of mercurial-scm.org, including static
links back to the non-hgweb site. I think making a custom template
might be easier than writing parsers and converters into manpage
formats (I've never really liked manpage formats to begin with though,
so maybe my opinion here doesn't count.)

I think as a matter of labour to be done, it would be easiest to
leverage hgweb and just write a custom mercurial-scm.org template for
it than anything else.

Speaking of default templates, maybe we should make something other
than paper the default. I don't like that it doesn't show full commit
messages and it overuses zebras when showing source code. The zebras
were something that mpm particularly insisted upon for a11y, but I
don't think this is a common a11y practice. (This is possibly a topic
for another time, though, or maybe it's related, not sure.)

> - Generate some doc index page with links to all the other generated
>   pages (categorized links to each command page, general links to
>   hgignore/hgrc, extensions, etc.)

hgweb already does this too, as you mentioned yourself.

https://www.mercurial-scm.org/repo/hg/help

> 3. Improve the website itself

Good ideas here. Just looks like a lot of work.

> 4. Make reference docs versioned

This would be helpful. Lots of other projects do this. Postgres and
Django and everything at Read The Docs comes to mind.

_______________________________________________
Mercurial-devel mailing list
[hidden email]
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
Reply | Threaded
Open this post in threaded view
|

Re: Mercurial docs improvements?

Ludovic Chabant
> > - This would let us see the doc for, say, `hg status` over at
> >   https://www.mercurial-scm.org/doc/hg-status.1.html
>
> As we discussed in IRC, that page already exists, but it's hard
> to find:
>
> https://www.mercurial-scm.org/repo/hg/help/status

Ah yes I forgot to mention that. There's a couple of things that I don't
like about this, though:

1) It doesn't work well (or at all) if we are thinking of having access
   to versioned docs.
2) I don't really like the idea of having an official Mercurial website
   that's an unholy mix of Flask views, generated html pages, wiki
   pages, and hgweb-served pages. We can try to make it look consistent
   (and thus transparent) by sharing templates and CSS styles, though,
   but, well, my gut feeling is that we should try and have a few moving
   parts as possible.
3) That URL is for the specific "status" command help of the "hg"
   repository. You can access the same page here for the "hg-committed"
   repository:
   https://www.mercurial-scm.org/repo/hg-committed/help/status So this
   duplicates things and makes things confusing for users, has a non-
   obvious URL, and, for pages like the "extensions" help
   (https://www.mercurial-scm.org/repo/hg-committed/help/extensions)
   lists the enabled/disabled extensions *for that repo*.

So as such, I don't think it's a good fit for a global, repo-independent
reference documentation.


> We can make the hgweb installation at mercurial-scm.org use whatever
> template we want. It makes sense to me to give it a template that
> matches the non-hgweb part of mercurial-scm.org, including static
> links back to the non-hgweb site. I think making a custom template
> might be easier than writing parsers and converters into manpage
> formats (I've never really liked manpage formats to begin with though,
> so maybe my opinion here doesn't count.)

Making a prettier default template for hgweb (and one that would be
consistent with the official website) would definitely be awesome
indeed, but it's outside the scope of what I want to achieve here. (as
such, for now at least, I'm going to ignore all your other comments
about hgweb :) )

I don't think we need to write parser and converters either. The hg help
pages can be generated into rST and that's probably all we need for now.

Although I could of course be mistaken, I frankly anticipate spending a
lot more time fiddling around with CSS, templates, and Makefiles that I
would with writing extra bits of code for HTML rendering or whatnot.

--
 l u d o .
 . 8 0 17 80
_______________________________________________
Mercurial-devel mailing list
[hidden email]
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
Reply | Threaded
Open this post in threaded view
|

Re: Mercurial docs improvements?

Jordi Gutiérrez Hermoso
On Mon, 2019-02-18 at 17:15 -0500, Ludovic Chabant wrote:

> So as such, I don't think it's a good fit for a global,
> repo-independent reference documentation.

There's an important dogfooding component here. If we think that the
hgweb docs are useless, then we should completely get rid of them and
just point people instead to the new docs you're building.

_______________________________________________
Mercurial-devel mailing list
[hidden email]
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
Reply | Threaded
Open this post in threaded view
|

Re: Mercurial docs improvements?

Ludovic Chabant
> On Feb 18, 2019, at 15:30, Jordi Gutiérrez Hermoso
> <[hidden email]> wrote:
>
> There's an important dogfooding component here. If we think that the
> hgweb docs are useless, then we should completely get rid of them and
> just point people instead to the new docs you're building.

I don’t believe the two should necessarily be the exact same thing —
hgweb shipping with documentation support is good for people who run
hgweb, especially because in some cases (like extensions help) it gives
them *contextual* documentation. But the official website is a bit
different.

At the end of the day, >95% of the documentation will come from
docstrings or help topics that are in the codebase, so the _source_ is
the same between hgweb and the website, and that's what matters most, I
think. Whether the Mercurial website is running hgweb to render the help
pages from those docstrings, or is running some bit of Flask code that
reads the same docstrings, or is just serving static http files that
were baked offline out of those docstrings... that's an implementation
detail. What matters is that people write command and topic help text
once and it shows up everywhere.

Now the question, to me, is what works best for the specific case that
is the Mercurial website. In my mind, offline-baked static http files
works best because they're performant and make it easy to handle
versioning. And it sounds a lot easier to do than having to modify hgweb
to have some "global" (non-repo-contextual) help section, figure a way
to map it to a URL that makes sense[1], and figure out how to handle
versioning (we're not going to run one hgweb instance per version of
Mercurial)... unless there's some easy way to bend hgweb to our will?


[1]: my guess is that the hgweb server is mapped to mercurial-
     scm.org/repo so this would mean the documentation URLs would have
     to start with "repo/" and the OCD in me is quite uncomfortable
     with that :)
_______________________________________________
Mercurial-devel mailing list
[hidden email]
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel