> On Feb 18, 2019, at 15:30, Jordi Gutiérrez Hermoso > <jord...@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 :) _______________________________________________ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel