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?

In T15012#1283, @MacFan4000 wrote:

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.

Sorry for the delay on this. Arcanist documentation lives in the rARC repo... I tried to regenerate it today and I had some permissions issues so I'll see what I can do.

As discussed in {E2}, we might add temporary banners to Diviner to state that we are rebranding. This would allow some time for us to handle the code rebrand and address the underlying Diviner issues before we edit everything twice.

This task may need to be triaged as high since we started by forking the Phabricator software, see also T15006: Re-brand Phorge.

I've re-generated the docs, and now we have two copies:

so:

1. need to delete the old ones, I didn't find a straight-forward way to do that
2. maybe do some http redirect from the old links to the new ones.

We should also generate the arcanist docs.

In T15012#2679, @MacFan4000 wrote:

We should also generate the arcanist docs.

Done - Arcanist and Libphutil.

In T15012#2678, @avivey wrote:

I've re-generated the docs, and now we have two copies:

so:

1. need to delete the old ones, I didn't find a straight-forward way to do that
2. maybe do some http redirect from the old links to the new ones.

That's because I changed the internal names of the books. I was planning on wiping our Diviner docs before I built the new ones. We may be able to use ./bin/remove with the book's PHID to remove these old books, though I haven't tested that yet.

I've tried locally with ./bin/remove , and it appears to work. To get the phid, I've visited the page and used "Actions -> Advanced -> View Handle" - I don't have this action available here.

If you view a book, then view source and search for PHID-BOOK then you should find a policy link. That's the PHID of the book you're viewing.

Done - deleted phabricator books.

I think we can close this now.