Skip to content
This repository has been archived by the owner on Mar 25, 2018. It is now read-only.

Documentation Tooling #12

Closed
chrisdickinson opened this issue Jun 23, 2015 · 7 comments
Closed

Documentation Tooling #12

chrisdickinson opened this issue Jun 23, 2015 · 7 comments
Assignees

Comments

@chrisdickinson
Copy link
Contributor

Hi – I'm taking this task for myself.

I'm going to investigate documentation tooling for this repository.

Goals:

  • Command to build docs into html format
  • Command to serve docs locally
  • Command to test docs (for broken links, spelling, etc.)

It's pretty likely these'll live as npm scripts (npm test, npm start, npm run export, etc.)

@chrisdickinson
Copy link
Contributor Author

Notes on tools: there have been two attempts to unbundle the existing doc tool from the core repo.

  1. I pulled out the tool from io.js at one point.
  2. @robertkowalski pulled it out of joyent/node.

I'm unconvinced that we can continue the "hand one file to the doctool, get one file back" approach — we should be checking things in a cross-document fashion (like including table of contents, whether links are broken, canonical named links, etc.) Additionally, the existing tool makes assumptions about the one-to-one-ness of module ⬌ documentation, which we're abandoning here.

@Qard
Copy link
Member

Qard commented Jun 24, 2015

👍 for link checking. It would also be good to check if a page exists that is not linked to from anywhere.

@bnb
Copy link

bnb commented Jun 24, 2015

Also 👍 for link checking. From the point of view of an inexperienced programmer, it seems like that would add a lot of complexity. Is that not the case?

@chrisdickinson
Copy link
Contributor Author

@bnb It shouldn't add much complexity. It's just a bit of extra bookkeeping for internal links. I'm not sure how I feel about checking external links, but even that would be pretty simple (it might take a bit longer to run, though!)

@Qard
Copy link
Member

Qard commented Jun 24, 2015

I'd pass on external links. Or, at most, make it a separate build task that only warns--other websites will go down, and it's not in our power to know or control exactly when that may happen.

@simov
Copy link

simov commented Jun 28, 2015

IMO we should have a thorough JSON structure in the first place. I just realized that the JSON docs generator actually parses the markdown, which is kind of nice, I guess, but how about having a good JSON structure in the first place?

I would like to have things such as inherits key, that alone will improve the docs dramatically, because you will be able to navigate easily through out the class hierarchy.

What type of object each method is returning, again it should be easy to navigate the hierarchy from there.

What type of object each event receives, same as above.

Also in case a method is accepting a map of options I would like to have each option with its default value and type (just search for "name": "request", in the generated JSON and see for yourself - currently all of it is tossed under the desc key)

Having a thorough JSON structure will allow us to generate markdown, html or just about any other visualization we might think of. The only remaining issue would be how to hook the non machine friendly parts of the docs to that structure (such as text and code examples).

EDIT

{
  "classes": {
    "net.Server": {
      "inherits": "events.EventEmitter",
      "methods": {
        "listed": {

        }
      }
    }
  },
  "utils": {
    "net.createServer": {
      "returns": "net.Server",
      "arguments": {
        "options": {
          "allowHalfOpen": {
            "type": "Boolean",
            "default": false,
          },
          "pauseOnConnect": {
            "type": "Boolean",
            "default": false,
          },
          "required": false
        },
        "connectionListener": {
          "type": "Function",
          "event": {
            "type": "net.Server",
            "name": "connection"
          },
          "arguments": {
            "socket": {
              "type": "net.Socket"
            }
          },
          "required": false
        }
      }
    },
    "net.connect": {
      "returns": "net.Socket",
      "arguments": [
        {
          "port": {
            "type": "Number",
            "required": true
          },
          "host": {
            "type": "String",
            "default": "localhost",
            "required": false
          },
          "localAddress": {
            "type": "String",
            "required": false
          },
          "localPort": {
            "type": "Number",
            "required": false
          },
          "family": {
            "type": "Number",
            "default": 4,
            "required": false
          },
          "connectionListener": {
            "type": "Function",
            "event": {
              "type": "net.Socket",
              "name": "connect"
            }
          }
        }
      ]
    }
  }
}

Wow this took me 10+ minutes, too much work even for writing it in JSON. My idea was to use the type and inherits keys for cross linking between modules. Anyway.

@chrisdickinson
Copy link
Contributor Author

Closing this in favor of #61

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants