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.
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.
We can change the styling, or apply a different theme, pretty easily. 
Oh, perfect then.
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
2 Likes
Good suggestions. I’m going to focus on a simply structure and automated deployment before tuning too much.
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.
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…
1 Like
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.
1 Like
Looks like it’s coming along nicely, I have some additional suggestions:
- 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
- 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.
1 Like
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.
http://nupic.docs.numenta.org/0.7.0.dev0/quick-start/index.html
TODO: Network API quick start docs.
1 Like
Docs might be down for a few hours today while DNS updates. New URLs will be:
- http://nupic.docs.numenta.org/ (nupic)
- http://core.docs.numenta.org/ (nupic.core)
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 …
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.
Yes, the engine propably need time.