Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

JSON documentation index listing #3668

Closed
mainerror opened this Issue · 16 comments

5 participants

@mainerror

The JSON representation of the documentation is pretty nice and useful, no doubt but it is too complicated to work with it the way it is now.

A listing of the JSON documents and their URL would help a lot when working with the JSON representation of the documentation.

Something like

{
  ...
  "synopsis": {
      "htmlURL": "http://nodejs.org/api/synopsis.html",
      "jsonURL": "http://nodejs.org/api/synopsis.json"
  },
  ...
}
@bnoordhuis

I suppose we could add some fields to ease discoverability. Currently, index.json looks like this:

{
  "type": "text",
  "text": "[Synopsis](synopsis.html)"
}

Which could be turned into this:

{
  "type": "text",
  "text": "[Synopsis](synopsis.html)",
  "name": "Synopsis",
  "htmlURL": "synopsis.html",
  "jsonURL": "synopsis.json"
}

@isaacs Opinions?

@isaacs

@bnoordhuis I think what you propose is ok. Perhaps the doc json generator should just generate its own index.json at the end, with links to all the json files it generated, and their top-level heading or something. I don't want the hard-coded nodejs.org url in there, though; it should be a relative link, so that it's easier to follow from other hosts without as much ceremony.

@mainerror

Yea, that sounds reasonable.

@bnoordhuis

@mainerror We take patches (hint, hint). :-)

@mainerror

@bnoordhuis I'm sure you do however since I don't quite understand the use of the current index.json representation I'm unlikely to start working on your JSON converter.

I'm especially confused about objects like

{
  "type": "list_start",
  "ordered": false
}

or

{
  "type": "list_item_start"
}

I just don't quite see the point in having those.

@isaacs

@mainerror The index.json is basically just the result of lexing https://raw.github.com/joyent/node/master/doc/api/_toc.markdown. What I was suggesting is that you have some code in the generator at tools/doc/json.js, which builds up the index.json file as it's creating each other file. It'll take a bit more massaging in the Makefile to get the dependency right, but even if we just .PHONY all the json docs, they build pretty fast.

@mainerror

I meant I don't really see the point in having those extra objects.

To me it looks like an attempt to mimic XML with JSON which is kinda defeating the point of JSON. Building a list out of the JSON response should not be the concern of the Node.js documentation build tool but of the client application consuming the JSON response.

So I would actually propose a change in the the representation which involves getting rid of such objects and just listing the entries with relative URLs to their HTML and JSON representations.

@isaacs

I meant I don't really see the point in having those extra objects.

I don't either. Remove them, and make a JSON index that is generated by building up a list as the documentation is created.

Make it the JSON index you'd love to see.

Sign the CLA and send a pull request. We can proceed from there to iron out the flaws in your design, and you can use that as a forum to ask questions that you encounter as you work with the code.

:)

@iapain

In my opinion something like this would be more intuitive.

{
  "source": "doc/api/index.markdown",
  "chapters": [
    {
      "title": "About the Docs",
      "url": {
          "html": "documentation.html",
          "json": "documentation.json"
      },
      "subchapters":[
        ...
      ]
    },
    ...
  ]
}
@isaacs

Ok. Please. I am literally begging you to write a patch at this point.

@iapain

@isaacs I'll take care of this.

@mainerror

I know this is low-priority. I'm pushing it anyway, maybe it has just been forgot.

@mainerror

Still no merge?

@jasnell
Owner

@mainerror ... did you still want to pursue this?

@iapain

@jasnell Here is PR #25540

@jasnell
Owner

Ok, got it. Sorry, been on vacation and still behind on catching up with github notifications. I'll review the PR this week. Going to close this particular issue, however, in favor of the new PR.

@jasnell jasnell closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.