nengo / nengo.github.io Goto Github PK

As pointed out in nengo/nengo#1520 there should be some process to ensure that we actually follow through with deprecation notices in the release cycle that they apply to. Currently this can be done by looking through CHANGES.rst.

Several projects have a PyPI badge on the overview page, Nengo SPA should have one too.

Step 8 “Build and upload the documentation” in “Making Python releases” should be removed, I believe. The documentation gets build and uploaded automatically by Travis CI when a tag is pushed, doesn't it?

When you go to any page with an anchor (e.g., https://www.nengo.ai/nengo/frontend-api.html#nengo.Ensemble), the related text is anchored to the top of the page, assuming the top navigation header is not there. But, with the top header there, part of the anchored text is occluded:

The page https://www.nengo.ai/getting-started/ refers to single_neuron.ipynb (recently renamed to single-neuron.ipynb) and links to the old (missing) notebook on the GitHub repo.

It may also be helpful to link to the corresponding page in the documentation (https://www.nengo.ai/nengo/examples/basic/single-neuron.html) so that a user knows where to look to see the rendered version of that same notebook.

See nengo/nengo#1633 for context and additional details.

The landing page for nengo.ai (index.rst) looks strange to me (Ubuntu 16.04, Google Chrome 74.0.3729.131) , not sure if it's intentional:

• Large font for all text, including bullets
• Double spaced bullet list
• Because of the large font and bullet spacing, the text doesn't align well with the images on the right.

Aside from the generic info that I've made issues for (and the info I haven't made issues for yet), we should also put all of the HTML files generated by Sphinx here.

There are a few reasons to put it here rather than in each project's gh-pages branch.

1. It's easy to write a script that clones a repo, checks out a branch, runs sphinx (or typedoc or whatever) and copies the output to a certain location in this repo. Doing it by checking out an orphan branch and pruning away the non-documentation stuff etc etc is not as easy to script.
2. The generated docs can get pretty big (2.5 MB zipped up for Nengo) so keeping them in a branch in each repo will negatively impact how long it takes to clone each project's repo. By keeping it all in this repo, it means that this one will be a pain to clone, but better for one repo (that many people won't ever clone) to be huge than to have all our repos be large.

Each subproject will be put in a subfolder off the root, and then within that subfolder, there will be a folder for each release. For example, for Nengo there'll be separate copies of the docs at

• https://nengo.ai/nengo/2.0.0
• https://nengo.ai/nengo/2.0.1

and so on. Similarly, there will be a https://nengo.ai/nengo_gui/0.2.0, etc.

The action items needed to get this working (once we have this repo set up in general) are to:

• Add scripts to check out and build docs for each project.
• Figure out how to link to those docs from the generic documentation in this repo.

Finding the Nengo core documentation (which is arguably more important than the documentation of the other subproject) could be easier. The fastest way at the moment seems to be to click on Nengo projects, scroll down and click that small Documetation button under Nengo core.

It also happened to me repeatedly that I clicked User Guide when I was actually looking for the Nengo core user guide (which is different).

This issue is motivated by:

• https://forum.nengo.ai/t/howto-cite-nengo/991
• The NEF text is still frequently cited incorrectly with the year 2004, since this is what google scholar uses for the top version.

We could provide Nengo+NEF citation instructions here for example: https://www.nengo.ai/publications/

Alternatively, could locate inside the Nengo core documentation, to mirror what Nengo-DL does here: https://www.nengo.ai/nengo-dl/project.html#citation

The more general parts of the CTN best practices guides could live in this repo.

• On GDrive: https://drive.google.com/drive/folders/0B8Q9l8-ja4yTNDY3eF9MZmJBMHM
• https://github.com/ctn-waterloo/best-practices

Have we decided what we're going to do for the model archive? I think we talked about this once and discussed how moving away from Drupal was a priority, but we weren't sure if it could be moved to github pages or not.

Ported from nengo/nengo#711; the document should take developers through all of the requirements and helper functions for developing a backend.

It should include an explanation of how to run Nengo unit tests, including how the Simulator.unsupported attribute works (which was the subject of nengo/nengo#711).

We should also link to existing backends, and provide a process for new backends to be included on the list.

Currently only Nengo, NengoDL, and NengoSPA are using the graphic logos. I guess we wait until we merge nengo/design#7?

Do we want the images to be webhosted (like the three are currently) or just drop these in _static?

Example 1: PyRates

Paper: https://www.biorxiv.org/content/biorxiv/early/2019/04/13/608067.full.pdf

Quote:

However, most often it is not possible to add new models or modeling mechanisms to this pool without considerable effort. This holds true especially, if one still wants to benefit from the parallelization and optimization features of the respective software... Unfortunately, the tools that provide such code generation mechanisms are limited with regards to the model parts they allow to be customized in such a way and the families of neural models they can express.

Rebuttal:
https://www.nengo.ai/nengo/examples/usage/rectified_linear.html

Example 2: DracuLab

Paper: https://www.frontiersin.org/articles/10.3389/fninf.2019.00018/full

Quote:

There are excellent simulators for firing rate networks (Aisa et al., 2008; Cofer et al., 2010; Rougier and Fix, 2012; Bekolay et al., 2014; Vitay et al., 2015; Tosi and Yoshimi, 2016), but it is unusual to find rate simulators that take into account connection delays.

Rebuttal:
https://arvoelke.github.io/nengolib-docs/nengolib.synapses.DiscreteDelay.html#nengolib.synapses.DiscreteDelay

Example 3: TODO ...

So far nengo.ai would redirect to the forum, but it now leads to a new main page that has no obvious link to the forum. That may confuse people who used nengo.ai (instead of forum.nengo.ai) so far to get to the forum.

Making a note for myself to make a PR later.

• Generally, we conform to pep8 and check this through flake8
• We use numpydoc conventions for docstrings
  • Parameters are ordered as in the call; attributes are alphabetically ordered (see nengo/nengo#959)
• Class members are ordered in a specific order (see nengo/nengo#959)

@s72sue made Nengo 2.0 versions of the "How to Build a Brain" tutorials. Would this website be a good place to link to them?

See: https://www.nengo.ai/nengo/examples/learn_associations.html

Tested on both Chrome and Firefox.

Is there a repo for the tutorials to make a PR/issue? I was running this tutorial and I get the error above when running the following code.

    nengo_dl.configure_settings(
        trainable=None, stateful=False, keep_history=False,
    )

Steps to reproduce:

• go to https://www.nengo.ai/documentation.html with full resolution (not the mobile view)
• mouse-over the "Documentation" menu to trigger the drop down
• try to click on a link that was just covered by the drop down (e.g., "Quick start guide")

@krisfrenette says the container / background for the dropdown is still present, even after the dropdown appears to go away.

• Reference semantic versioning.
• For backends, versions aren't tied to the frontend version number (summarize nengo/nengo#715)

I'll fix it later.

This page is designed to replace nengo.ca, so we should copy over any relevant content to this repo.

Additionally, the notes in nengo/nengo#763 should be implemented here when porting it over.

There should be a link to our forum.