apidocs: add ability to create a category summary page when there are subcategories

[dsokolsky]

In the apidoc, currently the transformation code has an assumption that if there are subcategories, then we will not create a category summary page. For many things, this is sensible. But we would like to have the ability to have the code generate one. For the js libraries like jsearch and Optic, this is desired. I think the part of the code that does this is here:

https://github.com/marklogic/RunDMC/blob/f0c42110ff0c2a448d420f408848e7c2b2b4cbfe/src/apidoc/setup/toc.xqm#L1376

The logic I would propose is as follows:

The content in the xml files is in /apidoc:module/apidoc:summary (note: this is not the same as the apidoc:summary elements under apidoc:function). The /apidoc:module/apidoc:summary element has a category and an optional subcategory attribute. It currently creates only subcategory pages if there is any apidoc:summary element that has both category and subcategory attributes. In this case, if there is an apidoc:summary element with just a category atribute, it is ignored.

The change in logic should be to create a summary page with the content in the /apidoc:module/apidoc:summary element with the category attr (but with no subcategory attrs).

For an example of this, see the jsearch.xml file which is in the 8.0 and later zip file under:

MarkLogic_8_pubs/pubs/raw/apidoc/jsearch.xml

The first apidoc:summary element in there has a category but no subcategory, but that content is never dispayed. To see what this currently looks lik, go to this page:

http://docs.marklogic.com/js/DocumentsSearch

In this case, what we want to do is create a new page and give the toc links to it with a name corresponding to the category (I think there is already code in there to come up with the name based on the attribute value).

If you need more details on this, talk to @kcoleman-marklogic or @gfurbush .

[popzip]

(see also https://bugtrack.marklogic.com/39803)

[kcoleman-marklogic]

I was just poking about in toc:functions-by-category on behalf of an unrelated problem, and I think the conceptual issue is this:

The code is quite determined to create a function list for any category/sub-category page it creates. If there are no sub-categories, or if the page is a sub-category page, this makes perfect sense. However, when there is a category page with sub-categories, the function list table is sometimes not a sensible thing to include because the functions can be part of different modules/classes, as is the case for CPF. Hence, in some distant past, a decision was made not to generate the category page at all.

I wonder if we could change the logic from "Don't generate a category page if there are sub-categories" to "Don't generate a function list if there are sub-categories". Maybe the change should only be applicable to lib modules, not builtins, IDK.

Such a change probably also implies cleanup of the lib module apidoc:summary elements for libraries with sub-cats since I doubt any of that content has ever seen the light of day, and some of it is bound to be nonsensical.

[kcoleman-marklogic]

The logic I long-windedly proposed above would be something like this;

if generating category page
  if no subcats exist then do what we do now (gen page)
  else if apidoc:summary for cat exists then gen landing page w that content
  else do what we do now (no landing page)
else if generating subcat page
  do what we do now (gen page)

For extra credit, we could include links to the subcat landing pages on the cat landing page, but I'm perfectly happy to treat that as separate, much lower priority RFE. :)

BTW, somewhere in the rats' nest must be code that knows how to do gen cat pages when there are subcats already because the REST Client API apidoc works. http://docs.marklogic.com/REST/client

[dmcassel]

Making progress... the page now shows up, but it's got the content of all the subcategory summaries. Onward....

[kcoleman-marklogic]

@dmcassel Should I expect further updates to the change you made for this? I recorded some issues in the pull request (which perhaps was the wrong spot, sorry). I know you have your hands full. Just wanted a status check.

[dmcassel]

@kcoleman-marklogic getting back to this today after some workshop travel.

[kcoleman-marklogic]

@dmcassel I am not feeling good about pushing this change live next week. It does not feel stable.

I think maybe the right thing to do with the pull req is merge it into the docapp branch and do any future fixes to this change there. That puts the burden on my team rather than yours to deal with staleness issues going forward. It also gives both you and us more time to make sure the change is working properly.

Whatcha think?