Mercurial docs improvements?

Ludovic Chabant ludovic at chabant.com
Mon Feb 18 21:25:16 EST 2019


> On Feb 18, 2019, at 15:30, Jordi Gutiérrez Hermoso
> <jordigh at octave.org> 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 :)


More information about the Mercurial-devel mailing list