Page MenuHomePhorge

Update Diviner documentation to reference Phorge
Open, NormalPublic

Event Timeline

Matthew triaged this task as Normal priority.Jun 18 2021, 16:38
Matthew created this task.
Matthew created this object with edit policy "All Users".

One thing that I think distinguishes these changes from T15006: Re-brand Phorge is that those changes are mostly intended to be submitted upstream in the hopes Phabricator accepts changes which enable more-easily re-branding the project. For Diviner I don't think that's something we can do since I'm guessing all the book content is effectively static.

In T15012#423, @speck wrote:

For Diviner I don't think that's something we can do since I'm guessing all the book content is effectively static.

That's correct. In fact, currently every copy of Phorge has an entire copy of the documentation (Located at src/docs) on check out. If you wanted documentation on a different install of Phorge, you could just run bin/diviner generate and it would look exactly the same as Diviner on upstream.

Phabricator had a task to make Diviner more generally useful, but that's not completed yet. I suspect it might be something we can eventually add to our workload here, as Diviner has a ton of untapped potential.

Both revisions are landed. We just need a pull on the upstream install to regenerate the documentation. @chris could you do the pull so I don’t break anything?

Note that I've been discussing with epriestley in the upstream regarding rebranding. His suggestion regarding diviner is to introduce a ReMarkup rule that allows for using e.g. ${{{ project.name }}} which is then swapped out during rendering, allowing the diviner documentation to reference a non-descript project name that is filled-in when generated/rendered. I think that's something we should consider, and I think will be something that gets submitted/accepted in the upstream.

In T15012#766, @speck wrote:

Note that I've been discussing with epriestley in the upstream regarding rebranding. His suggestion regarding diviner is to introduce a ReMarkup rule that allows for using e.g. ${{{ project.name }}} which is then swapped out during rendering, allowing the diviner documentation to reference a non-descript project name that is filled-in when generated/rendered. I think that's something we should consider, and I think will be something that gets submitted/accepted in the upstream.

I've been working on a diff for this. Diviner is rough as it doesn't parse book titles or descriptions using Remarkup, so I'll also have to make a change to the Diviner engine as well...

I've been working on a diff for this. Diviner is rough as it doesn't parse book titles or descriptions using Remarkup, so I'll also have to make a change to the Diviner engine as well...

Ah, yea... I actually have a change in our company's Phabricator instance that customizes the rendering of titles on diffs and audits, though it doesn't use remarkup rendering on them but just optionally creates links to our external task system. I'm not sure what would be a good solution here, as using remarkup doesn't necessarily seem like the right approach.

The Server also needs to periodically rebuild the Diviner Books to keep them in sync with Source Code. Eg. just set up a crontab entry. Or later, if more traffic is on the page: rebuild it once a commit affecting the Docs is committed.

Right now Diviner shows the original Phabricator Documentation, while it is already changed to Phorge in the source.

I will note that also the tech docs aren’t fully generated since there should be docs for most of the phorge/phabricator classes. Also the arcanist docs aren’t generated at all.

We should include the Diviner and tech docs generation as part of the upgrade process of this server, that should ensure it's always up to date.

@MacFan4000 do you know how the tech docs are supposed to be generated? Is it part of ./bin/diviner server script?