938169 - Auto generate firefox preference documentation pages

Status: RESOLVED WONTFIX

(developer.mozilla.org Graveyard :: General, defect)

Description

[Chris Mills [:cmills]]

What problems would this solve?
===============================
We want to create a comprehensive reference of all of the preferences available under about:config. We get asked about these settings a lot, so it would be really useful to have. There are already some located under 

https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/Preference_reference

But there are about 2000 preferences, so creating all the subpages by hand would be a nightmare.

What we'd want to do is read all the different preference titles out of the browser source code, and for each one create a subpage underneath

https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/Preference_reference

so for example

* https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/Preference_reference/accessibility.tabfocus
* https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/Preference_reference/browser.altClickSave
* etc.

This could be done using Les Orchard's PUT API:

 https://developer.mozilla.org/en-US/docs/User:lmorchard/PUT-API

Each page should have the following template auto-filled into it:

<div class="summary>
  <p>Summary</p>
</div>

<dl>
  <dt>title</dt>
  <dd>definition</dd>
</dl>

<h2 id="Values">Values</h2>

<dl>
  <dt>title</dt>
  <dd>definition</dd>
</dl>

Who would use this?
===================
developers and writers

What would users see?
=====================
not a lot

What would users do? What would happen as a result?
===================================================
better docs

Is there anything else we should know?
======================================
nope

Comment 1

[Chris Mills [:cmills]]

Correction:

Each page should have the following template auto-filled into it:

<div class="summary">
  <p>Summary</p>
</div>

<dl>
  <dt>title</dt>
  <dd>definition</dd>
</dl>

<h2 id="Values">Values</h2>

<dl>
  <dt>title</dt>
  <dd>definition</dd>
</dl>

Comment 2

[Les Orchard [:lorchard]]

Do we have a browser source file in particular that lists all the prefs? Could probably build a scraper to source the pref names if we have a URL to look at.

Comment 3

[Les Orchard [:lorchard]]

Adding some CCs so more can join in the fun

Comment 4

[Jean-Yves Perrier [:teoli]]

A lot of these about:config entries are temporary and/or created each week.

How do you plan to keep this updated?

Comment 5

[Jean-Yves Perrier [:teoli]]

(In reply to Les Orchard [:lorchard] from comment #2)
> Do we have a browser source file in particular that lists all the prefs?
> Could probably build a scraper to source the pref names if we have a URL to
> look at.

No, some are hardcoded in c++ (in different ways, scattered all around our codebase), some are in the idls, and surely some are in other way.

Comment 6

[Les Orchard [:lorchard]]

(In reply to Jean-Yves Perrier [:teoli] from comment #5)
> (In reply to Les Orchard [:lorchard] from comment #2)
> > Do we have a browser source file in particular that lists all the prefs?
> > Could probably build a scraper to source the pref names if we have a URL to
> > look at.
> 
> No, some are hardcoded in c++ (in different ways, scattered all around our
> codebase), some are in the idls, and surely some are in other way.

Okay, that limits what we can do automatically with a script. If we don't have a machine readable inventory or registry from which a script can work, we can't automatically create/update a set of pages.

Comment 7

[Chris Mills [:cmills]]

(In reply to Les Orchard [:lorchard] from comment #6)
> (In reply to Jean-Yves Perrier [:teoli] from comment #5)
> > (In reply to Les Orchard [:lorchard] from comment #2)
> > > Do we have a browser source file in particular that lists all the prefs?
> > > Could probably build a scraper to source the pref names if we have a URL to
> > > look at.
> > 
> > No, some are hardcoded in c++ (in different ways, scattered all around our
> > codebase), some are in the idls, and surely some are in other way.
> 
> Okay, that limits what we can do automatically with a script. If we don't
> have a machine readable inventory or registry from which a script can work,
> we can't automatically create/update a set of pages.

Right, ok ;-)

So basically this is going to be very difficult to impossible to do. Is there any way to separate out the more important/permanent prefs, versus the highly temporary ones?

Comment 8

[Les Orchard [:lorchard]]

What might be a decent consolation prize is that if you *can* assemble an inventory somehow, even if done manually - say, as a Google Doc or CSV export - we could still feasibly build a tool that creates & updates a bunch of pages in bulk.

Comment 9

[Luke Crouch [:groovecoder]]

Erik Rose has been working on DXR ... Erik, could DXR detect about:config preferences in the code-base to automate creating documentation pages for them?

Comment 10

[Les Orchard [:lorchard]]

(In reply to Jean-Yves Perrier [:teoli] from comment #4)
> A lot of these about:config entries are temporary and/or created each week.
> 
> How do you plan to keep this updated?

That's a good question. I hadn't even thought about this, beyond a one-off script. Would be handy to have this as a repeatable process if we have a handle on a source of truth for about:config entries. (i.e. Are these all inventoried somewhere in a header or some source file in Gecko?)

A periodic script could generate new pages from a skeleton template, add a tag that signals that they're in need of fleshing out. And, the scrip could somehow tag or alter existing pages for prefs that are detected as having been deleted or deprecated.

What we do here, exactly, boils down to two things I think:

1) How do we want this to work on an ongoing basis, from a content management & writing process perspective?

2) How can we track changes in the set of about:config entries in a machine readable way?

Comment 11

[Erik Rose [:erik][:erikrose]]

I see 2400 of them in http://dxr.mozilla.org/mozilla-central/source/modules/libpref/src/init/all.js and another 606 in http://dxr.mozilla.org/mozilla-central/source/browser/app/profile/firefox.js. A lot of them are preceded by comments. That's scrapeable and should certainly get you started.

DXR's plugin interface allows for running arbitrary code over the whole codebase every night. What gets spit out is currently assumed to be one HTML file per source code file, but I would be very happy to have a hook added for emitting aggregate reports like this one.

Comment 12

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.