NuPIC API Docs prototype

documentation

#1

What do you folks think about this documentation format compared to our current version?

This is just a prototype, but I think this is the direction we’re going.


Why isn't HTM mainstream yet
#2

I definitely like that everything’s in the center right when I load up the page. Also the main page is much better than the old “This documentation is a work in progress”

However, it does have black text on a white background, which can cause eye strain, and makes reading much harder for people with dyslexia [link]. I think current version has better colors half the time.


#3

We can change the styling, or apply a different theme, pretty easily. :thumbsup:


#4

Oh, perfect then.


#5

I much prefer the new style since personally I find package and class hierarchies annoying to look through in docs since you sort of have to know what you’re looking for before you can find it.

I think that sphinx format is really good for adding extra information, notes and usage. Although I can suggest a few improvements:

  • Have each function link to its source code (ala Haskell documentation).
  • Make the TOC fixed, so it remains visible when you scroll down.
  • Maybe add some extra documentation pages for (since a lot of information about nupic is fractured between the wiki, youtube, forums, and now potentially generated documentation):
  • Quick start
  • Building from source
  • Running unit tests

#6

Good suggestions. I’m going to focus on a simply structure and automated deployment before tuning too much.


#7

NuPIC Core API docs prototype:

http://rhyolight.github.io/nupic.core/

The style will likely change. I’m trying to keep the structure between these two implementations as close as possible.


#8

:+1:


#9

Done with NuPIC

NuPIC API docs are now automatically created for tip of master at http://numenta.github.io/nupic/ for every checkin to master.

Will continue work on NuPIC Core…


#10

Done with NuPIC Core

NuPIC Core API docs are also now automatically created for tip of master at http://numenta.github.io/nupic.core/ for every checkin.


#11

Looks like it’s coming along nicely, I have some additional suggestions:

  1. Add a quick start guide, this would make is easy for people to jump in and get something working (along with a brief explanation):
  • How to install using pip
  • Code for creating an OPF model using some default parameters
  • Load some data
  • Run that model and get output
  • Modify that model to use some different encoders and data, run again
  1. Make the TOC expandable, like in pyopencl docs: https://documen.tician.de/pyopencl/ , this makes it easier to jump around the documentation without having to navigate backwards when you have them open as a resource

It might seem a bit radical, but perhaps the wiki could be kept for those who want to develop the main nupic codebase, and the new docs for users of nupic? It would mean a significant migration and an increase in difficulty in updating the documentation, but it would certainly separate the concerns well and make it easier for people to get started.


#12

I appreciate your suggestions and the example pages you gave me. I’m working on expandable TOC now. I will do a quick start guide as well.

I’d really like to funnel everyone here to HTM Forum. It can double as a wiki. Any important pages on the current wiki will be moved here and will still be editable by forum members. I will make an announcement here when I start moving content over. It will also allow discussion about the wiki pages, which is nice.


#13

http://nupic.docs.numenta.org/0.7.0.dev0/quick-start/index.html

TODO: Network API quick start docs.


#14

Docs might be down for a few hours today while DNS updates. New URLs will be:


#15

Another thing is that google doesn’t find the doc when you type “nupic doc”.
I don’t know if it can be easily fixed …


#16

Does it take some time for search engines to pick up new sites? I get hits when I search “nupic api docs”, but they are links to old versions of the docs that existed over a month ago. Someone should check again in 6 months.


#17

Yes, the engine propably need time.