[MXNET-244] Update RaspberryPI instructions

[larroy]

Description

Update RaspberryPI instructions
#7852

Checklist

Essentials

Please feel free to remove inapplicable items for your PR.

• The PR title starts with [MXNET-$JIRA_ID], where $JIRA_ID refers to the relevant JIRA issue created (except PRs with tiny changes)
• Changes are complete (i.e. I finished coding on this PR)

[larroy]

@aaronmarkham

[szha]

LGTM. I will wait for @aaronmarkham's comment on this.

[aaronmarkham]

Some minor suggestions. Also please test this. The install page is brittle.

[aaronmarkham]

End with period

[aaronmarkham]

Move that up above the command.
The following command will build...

[aaronmarkham]

resulting artifact

[aaronmarkham]

Test this. The install page's markdown functionality is broken due to how the selector works.

[larroy]

Can you tell me how to test?

[larroy]

@aaronmarkham ping

[aaronmarkham]

Follow these directions to setup a test server and build the docs. Test the selector to make sure content shows up when you click on the different install options.

https://github.com/apache/incubator-mxnet/blob/master/docs/build_version_doc/README.md#setting-up-a-docs-dev-server

[aaronmarkham]

If you check Jetson, those instructions are gone.
http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/install/index.html?platform=Devices&language=Python&processor=GPU

[larroy]

@aaronmarkham I don't have access to that url

[aaronmarkham]

I'm not sure what's up with that preview. It does that to me sometimes too. Try this link:
http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/PR-11562/2/install/index.html?platform=Devices

[aaronmarkham]

@larroy - I'd remove the ## and just ** bold stuff for section headers. You could also use html styles and nested <div> tags if you really wanted to. I believe the selector hacks the markdown or maybe the h1 and h* tags to do its magic. I don't really know, other that it is a total PITA.

Try that and if it doesn't work to reveal the missing section, let me know and I'll dig into and try to fix it for you.

[larroy]

I tried to run the "deploy_docs" function using docker via ci/build.py but had errors in the scala part.

[aaronmarkham]

CI seems to be running fine for the docs job...
I guess when you try to run that script manually you get an error?
Have you run this first?
./ci/docker/install/ubuntu_scala.sh

There was a new scaladocs step added to the build fairly recently which does a make scalapkg prior to scaladocs being run. You'll need all of the scala deps to run that.

[aaronmarkham]

Also, this is a recent issue for running make docs:
#11662

[larroy]

This works, we should add to the instructions

ci/build.py -p ubuntu_cpu /work/runtime_functions.sh build_docs master master master "http://mxnet.incubator.apache.org/"

@aaronmarkham when I open the built documentation the page is empty, any ideas what I'm doing wrong?
open "docs/build_version_doc/apache_mxnet/docs/_build/html/index.html"

I click install
and

file:///home/piotr/devel/mxnet/mxnet/docs/build_version_doc/apache_mxnet/docs/_build/html/install/index.html

Is empty.

[aaronmarkham]

@larroy - You really, really want that Docker route don't you? It didn't work because build.py is broken. I couldn't figure it out how to patch it several months back, so that's why I rewrote the docs build pipeline. Its logic prevented fixing some other bugs. I imagine now that I've nailed down most of the dependency issues and logical dilemmas, you could tack on the Docker parts to current scripts. I should have deleted build.py, but I didn't because I wanted to keep it around as a reference implementation, even if it is broken now.

Please try out my new script and see if that works for you. It's in a pending PR, #11670. I made this because you and a few other people were having docs build/dependency problems. I hope it helps. Here are the instructions.

If you want to try it out right away, before it gets merged:

git clone --recursive https://github.com/aaronmarkham/incubator-mxnet.git mxnet
cd mxnet/docs/build_version_doc
git checkout clojure_doc_build
./setup_docs_ubuntu.sh
cd ../../
make docs USE_OPENMP=1

[Roshrini]

@larroy @aaronmarkham Can you provide update on this PR? Still working on it or ready to be merged?

[larroy]

@aaronmarkham the reason to use docker is not to damage and change your system configuration
I'm trying your instructions now but I think the docs should be built in the same fashion that we do for everything else using the infrastructure on the ci/ folder and dockerfiles.

[larroy]

root@241aff320a43:/mxnet# make docs USE_OPENMP=1
make -C docs html
make[1]: Entering directory '/mxnet/docs'
Makefile:29: *** The 'sphinx-build' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the 'sphinx-build' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/.  Stop.
make[1]: Leaving directory '/mxnet/docs'
Makefile:534: recipe for target 'docs' failed
make: *** [docs] Error 2

[larroy]

python-sphinx and maven seems to be missing from the script, also there's dependencies missing for scala.
I strongly recommend we move these scripts to docker so the environment is contained and reproducible.

[larroy]

make[2]: Leaving directory '/mxnet'
Execute "cd /mxnet/docs/../scala-package; scaladoc `find . -type f -name "*.scala" | egrep "\/core|\/infer" | egrep -v "Suite"`; exit 0"
/bin/sh: 1: scaladoc: not found
Execute "rm -rf /mxnet/docs/_build/html/api/scala/docs"
Execute "mkdir -p /mxnet/docs/_build/html/api/scala/docs"
Execute "cd /mxnet/docs/../scala-package && mv -f index /mxnet/docs/_build/html/api/scala/docs"
mv: cannot stat 'index': No such file or directory
Command 'cd /mxnet/docs/../scala-package && mv -f index /mxnet/docs/_build/html/api/scala/docs' returned non-zero exit status 1

Exception occurred:
  File "/mxnet/docs/mxdoc.py", line 56, in _run_cmd
    raise err
CalledProcessError: Command 'cd /mxnet/docs/../scala-package && mv -f index /mxnet/docs/_build/html/api/scala/docs' returned non-zero exit status 1
The full traceback has been saved in /tmp/sphinx-err-KlI9Pk.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:75: recipe for target 'html' failed
make[1]: *** [html] Error 1
make[1]: Leaving directory '/mxnet/docs'
Makefile:534: recipe for target 'docs' failed
make: *** [docs] Error 2

More problems. This process is way too complicated.

[larroy]

@aaronmarkham can you check on the deployed documentation here if you see any problems? http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/install/index.html?platform=Devices&language=Python&processor=CPU

[aaronmarkham]

You need the docs deps first. They're all in the Ubuntu setup script in build_version_doc. Or you can follow the CI deps.

[aaronmarkham]

@larroy, the CI and the setup scripts are aligned afaik. Scaladocs and Sphinx are in both dependencies lists.
Unfortunately, the docs system is very complicated. My recent PRs attempt to address this. Please try out the latest. #11990

[larroy]

But can we merge this? Does the output from the PR link look good to you?

[aaronmarkham]

I get accessed denied on that link

[larroy]

Fixed link: from the deploy phase of CI: http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/PR-11562/2/index.html

[aaronmarkham]

Jetson content is gone:

Should have this....

Dude, I know, I know. That install page is a nightmare. Building the website is way too complicated. Let's fix it!
But first let's get this PR out...

Note that your hashes for markdown headers are like the only ones in the doc. That's because the js running on that page uses them for its dastardly logic. You cannot. Take them out. Use html tags only, or better yet, just use BOLD or italics and don't mess with those headers. Then it will likely work.

[larroy]

Yes. This is quite frustrating. I was close to write an email to to dev but hold off. Any ideas how to make this easier? I will have a look again next week at this. This weekend I need a break.

[szha]

it's getting better now as the page's structure is cleaner. on the other hand it's a bit dangerous to rely on human judgement alone. @aaronmarkham any idea how we may add tests?

[aaronmarkham]

I think we need to replace that selector with something that plays nice. It shouldn't break markdown structure, or cause hours of dev time to troubleshoot... which it currently does.

[larroy]

Anything else to do? Seems jetson content is now working:

http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/install/index.html?platform=Devices&language=Python&processor=CPU

[aaronmarkham]

I used this preview instead, but it looks good!
http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/PR-11562/4/install/index.html
I'm curious what you changed. It looks like you were able to leaving in the markdown header tags.

[larroy]

See the patch, there was an empty Jetson tx2 section on the bottom of the file. The JS selector converts the button name to lowercase and spaces to - as seen in the js file. Now the divs make sense.