Docs Reorg

[xchoo]

Motivation and context:
Documentation was reviewed as part of the work to officially release nengo-fpga (and associated hardware repos). This PR is just for the reorganization of the existing docs to fulfill the requirements discussed at the reorganization meeting

How has this been tested?

• Compiled on local machine. Compiles without errors.
• Checked built docs in web browser. Looks fine.

How long should this take to review?
Quick

Where should a reviewer start?
Start by building the docs, then looking through each section one by one.

Types of changes:
Non-code change (touches things like tests, documentation, build scripts)

Checklist:

• I have read the CONTRIBUTING.rst document.
• I have updated the documentation accordingly.
• I have included a changelog entry.
• I have tested this with all supported devices.
• N/A I have added tests to cover my changes.
• N/A I have run the test suite locally and all tests passed.

Still to do:

[bmorcos]

The file path doesn't render correctly. I'm seeing ssh/authorized_keys... I guess ~ is a special char in rst?

[arvoelke]

I think you want double backticks (``...``) for code samples. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

[bmorcos]

For the NengoFPGA docs we're using double ticks for code/commands and single ticks for files/paths as the render differently.

[arvoelke]

I don't think single backticks are strictly valid markup as you are using them, as it's meant to be used for links/etc. The parser might be smart enough to render something reasonable in most cases, but I suspect this is one of those cases where it's not. I'm pretty sure the other nengo projects use double backticks for everything and make no distinction between paths and commands (example). If the path has some important meaning you want to draw attention to, it might be worth creating a section in the doc and making it an interlink.

[xchoo]

Have I mentioned how much I hate rst? The documentation is piss poor, the error's are terrible to debug, and it's so hard to search for how to do even the simplest things. 😠

[arvoelke]

I looked a little more closely and when you run the build_sphinx command you should be seeing the following warning: WARNING: py:obj reference target not found: /.ssh/authorized_keys. It's parsing these as links, and rendering it as such without the actual hyperlink because they don't exist. If you really want a separate style for paths you might want to look into custom text roles as an option. But I'm not an expert on reStructuredText either so maybe there's a better option.

[xchoo]

I don't get any warnings when I build it using the build_sphinx command.

[bmorcos]

Thanks for pointing it out Aaron, I guess I just noticed the different rendering style and didn't think that it's because single backticks are for sphinx keywords (like links).

Let's leave it for now but we should at least discuss changing this going forward before we do our next release @xchoo

[xchoo]

I build it with -vW (verbose, turn warnings into errors) as well. So if I did get a warning, it should have tripped up and stopped the compile.

[arvoelke]

You might want to add nitpicky = True to docs/conf.py as we do for the other projects. This should reveal the above warning I mentioned as well as some others. Currently on this branch:

/home/arvoelke/CTN/nengo-fpga/docs/api.rst:8: WARNING: py:obj reference target not found: FpgaPesEnsembleNetwork
/home/arvoelke/CTN/nengo-fpga/docs/api.rst:23: WARNING: py:obj reference target not found: FpgaPesEnsembleNetwork
/home/arvoelke/CTN/nengo-fpga/docs/api.rst:32: WARNING: py:obj reference target not found: 02-mnist_vision_network
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:64: WARNING: py:obj reference target not found: authorized_keys
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:89: WARNING: py:obj reference target not found: nengo-fpga
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:100: WARNING: py:obj reference target not found: authorized_keys
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:127: WARNING: py:obj reference target not found: *.pub
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:133: WARNING: py:obj reference target not found: fpga_config
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:140: WARNING: py:obj reference target not found: ssh_pwd
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:140: WARNING: py:obj reference target not found: ssh_key
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:140: WARNING: py:obj reference target not found: ssh_key
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:152: WARNING: py:obj reference target not found: ssh_pwd
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:152: WARNING: py:obj reference target not found: ssh_key
/home/arvoelke/CTN/nengo-fpga/docs/appendix.rst:175: WARNING: py:obj reference target not found: IPv4 Address
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:57: WARNING: py:obj reference target not found: fpga_config
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:57: WARNING: py:obj reference target not found: nengo-fpga
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:57: WARNING: py:obj reference target not found: [host]
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:67: WARNING: py:obj reference target not found: [host]
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:75: WARNING: py:obj reference target not found: ip
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:90: WARNING: py:obj reference target not found: [pynq]
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:90: WARNING: py:obj reference target not found: [pynq]
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:90: WARNING: py:obj reference target not found: [de1]
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:131: WARNING: py:obj reference target not found: ssh_user
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:131: WARNING: py:obj reference target not found: fpga_config
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:160: WARNING: py:obj reference target not found: fpga_config
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:166: WARNING: py:obj reference target not found: dna_extractor.py
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:166: WARNING: py:obj reference target not found: nengo_fpga
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:166: WARNING: py:obj reference target not found: nengo-fpga
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:166: WARNING: py:obj reference target not found: fpga_config
/home/arvoelke/CTN/nengo-fpga/docs/getting_started.rst:166: WARNING: py:obj reference target not found: nengo-fpga
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:8: WARNING: py:obj reference target not found: FpgaPesEnsembleNetwork
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:43: WARNING: py:obj reference target not found: post
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:77: WARNING: py:obj reference target not found: nengo_fpga
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:94: WARNING: py:obj reference target not found: nengo_fpga
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:113: WARNING: py:obj reference target not found: nengo-fpga/docs/examples
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:118: WARNING: py:obj reference target not found: nengo-fpga/docs/examples
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:122: WARNING: py:obj reference target not found: # --- BOARD SELECT ---
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:122: WARNING: py:obj reference target not found: de1
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:122: WARNING: py:obj reference target not found: pynq
/home/arvoelke/CTN/nengo-fpga/docs/usage.rst:122: WARNING: py:obj reference target not found: fpga_config

This should show all occurrences of broken inline links that render differently from inline code. The nengo-bones project will soon template out conf.py with nitpicky = True and so this is a heads-up for what you might see then. There is also some info here about how you could catch this using the default_role: sympy/sympy#13519.