How to create an ECR documentation viewer for your project

The ECR repo contains two projects that can be downloaded and used to create local, viewable documentation.  This is great when you want to see what things will look like before you push your code to the ECR.

First step is to create a folder so that you can checkout the edrdocs and sphinx projects.  Might as well call this "docviewer" and create it in your development tree.

cd ~/development/leidos
mkdir docviewer
cd docviewer

Then you need to clone two repositories, and then make sure to checkout master on the edrdocs - that branch is clean, the other branches have some ECR project configuration that you don't need.

git clone ssh://git@ecr.sdo.leidos.com:7998/edr/sphinx.git
git clone ssh://git@ecr.sdo.leidos.com:7998/edr/edrdocs.git
cd edrdocs
git checkout master

This next step will put a link in your edrdocs source folder, back to the project that you want to test.  Lets say your project is called my-great-project and its in ~/development/leidos/my-great-project.  All you need to do is make a soft link in the edrdocs/source folder, to your project.  At this point, you should be sitting in your edrdocs folder, having just checked out the master branch.

ln -s ~/development/leidos/my-great-project source/my-great-project

Next, you need to add your project to the source/projects.rst file.  Just replace the line with ./EDR.edrdocs/README, with a reference to your README.md or index.rst file.  Remember - do not include a file extension on your reference inside the source/projects.rst file! your final will look something like this:

Project List
============

.. toctree::
   :maxdepth: 1
   :caption: Projects

   ./my-great-project/docs/index

or 

Project List
============

.. toctree::
   :maxdepth: 1
   :caption: Projects

   ./my-great-project/README

Now you can build your documentation using the pre-built builders in the sphinx project.

macosx: ../sphinx/sphinx-build-macosx.zip -b html source _build
ubuntu: ../sphinx/sphinx-build-ubuntu.zip -b html source _build

If everything goes well, you can now view your documentation by opening the _build/index.html file in your browser.

macosx: open _build/index.html

Troubleshooting... 

The output from the sphinx builder will contain a bunch of stuff that makes absolutely no sense the first time you run it.  All that stuff comes from a plugin that is creating a downloadable reference to one of the spreadsheets.  You can ignore that.  It should only be displayed the first time you generate docs or if you wipe out your _build folder.

If you see something like this:  WARNING: document isn't included in any toctree then that is something to pay attention to.  You will see one of these for the governance.xlsx, and that one is ok and expected.  But if you get that for one of your own files, then you have a minor configuration problem.

Either your soft link is not correct, or your reference to your project file is not correct in the projects.rst.  To test your softlink, just try to change directory there.

pushd source/my-great-project
# if that works then...
popd

If the soft link is not correct, try to recreate it using a full file path.

rm source/my-great-project
ln -s /my/full/path/home/development/leidos/my-great-project source/my-great-project

If you don't have a soft link issue, then you probably did not set up the projects.rst file correctly.

Make sure that your document reference does NOT have a file extension.  ./my-great-project/README.md (bad) ./my-great-project/README (good) 

Also, make sure that your path starts with a dot.  ./my-great-project/README (good) 

Other than that, your own project doc folder just needs to be internally consistent, and follow the same patterns.

One thing to note: references to documentation that go up and out of the edrdocs tree wont work.  Everything needs to be a relative path that extends down from edrdocs/source.  This means that your index.rst file can reference ../README, but not something on an alternate path.  Thats why we put a soft link to your project in there.  Otherwise we would do:

Project List
============

.. toctree::
   :maxdepth: 1
   :caption: Projects

   ../../somepath/higher/and/back/down/my-great-project/README <- absolute paths, and paths that to up past edrdocs/source won't work.

Windows Set up

Since windows does not support (easily), symbolic links, and windows 7 does not support long file names / paths, there is no simple way to create a "sphinx-build-windows.zip" style of document builder.  These instructions should let you do the same thing, but using python directly.

1. Make sure you have python 3.5+ installed
2. Make sure you have virtualenv installed
   1. pip install virtualenv
3. Create a virtual environment
   1. virtualenv sphinx-env
4. Enter the virtual environment
   1. sphinx-env\Scripts\activate
5. Install the rest of the products
   1. pip install sphinx
   2. pip install recommonmark
   3. pip install sphinxcontrib-excel-table-enhanced
6. You may need to deactivate your virtual environment and reenter
   1. deactivate
   2. sphinx-env\Scripts\activate

7. Test sphinx

   1. sphinx-build --help

      1. If you get a help screen here - then you are good to go

      2. If not, then you will need to debug your python environment

         
         

Now that you can run sphinx, instead of making a soft link to your project, you will have to copy your project to the edrdocs/source folder.  This is the only way that sphinx will find your files.  The project.rst set up will be exactly the same as above.  If you are on Windows 10, you may be able to create a soft link (windows calls this a symbolic link), try that first.

Once you have copied your project to the source folder, or created a soft link, then you can run sphinx like this:

sphinx-build -b html source _build

You can then view your documents by opening _build\index.html