Page MenuHomePhabricator

doc: Generate separate commands/topics/extension web pages.
Needs ReviewPublic

Authored by ludovicchabant on Sep 30 2020, 5:35 PM.


Group Reviewers

Diff Detail

rHG Mercurial
Lint Skipped
Unit Tests Skipped

Event Timeline

ludovicchabant created this revision.Sep 30 2020, 5:35 PM
ludovicchabant added a comment.EditedSep 30 2020, 5:40 PM

Hi there... this patch is a proof of concept, and probably entirely the wrong approach since I was learning Makefiles almost from scratch as I was doing it (and then by the end realized it only works with recent versions of Make). But I'd like to put the basic idea of the change up for review at least before I continue working on it.

The basic idea is that the Mercurial reference page is too damn big and unwieldy. Its size also makes it hard to search for something only for a given command. One could search through the help output in a terminal but there is tremendous value in having a well organized and friendly website. Anyway, this change makes it possible to spit out separate web pages for each command, topic, and extension, along with a classified index page that links to all of them.


I like it. Did you intend this as an RFC, or for landing?

ludovicchabant added a comment.EditedDec 2 2020, 5:57 PM

Derp... phabricator didn't send me any email notification....

Anyway, if the implementation is roughly ok we can do a code review and queue it for next release. If not, I can redo it using a better approach? I'm not sure what "RFC" and "landing" mean in the specific context of the mercurial release workflow, so whichever one is more appropriate is fine by me! The main things I'd like to have feedback on are:

  1. The method I'm using here requires a recent Make (for instance, the one that ships by default on macOS won't work). I don't know if there's a better way to do this?
  2. This generates a bunch of intermediate and final files, which increases the make docs time. I don't know if process time is an issue here, or if it's OK because it's run only once per release?
  3. I took a bit of creative freedom for the format of the new pages. This is easy to iterate upon a bit later but it's worth taking a look at the output in case you have any opinions.


I'm fine with this as long as it still works on Python 3. Can you confirm this works under Python 3? Maybe rebase it to @ for completeness, since it's been a while.

Sorry for slow responses.