Integration of sasmodels documentation with SasView

[ajj]

oops - closed wrong ticket

[butler]

I think all the GUI access to docs has been changed to point to new docs

[butler]

Sasmodels is now moving to release + 1 (basically 4.0)

[butler]

clearly part of core task "integrating sasmodels into SasView." Therefore moving to blocker

[smk78]

20/03/2016 10:45 GMT

SASMODELS documentation now builds without any errors.

Running Sphinx v1.3.1
making output directory…
C:\Code\sasmodels\doc
C:\Code\sasmodels\doc\_extensions
C:\Code\sasmodels

C:\Anaconda2\python27.zip
C:\Anaconda2\DLLs
C:\Anaconda2\lib
C:\Anaconda2\lib\plat-win
C:\Anaconda2\lib\lib-tk
C:\Anaconda2
C:\Anaconda2\Library\bin
c:\anaconda2\lib\site-packages\sphinx-1.3.1-py2.7.egg
c:\anaconda2\lib\site-packages\setuptools-18.4-py2.7.egg
C:\Anaconda2\lib\site-packages
C:\Anaconda2\lib\site-packages\PIL
C:\Anaconda2\lib\site-packages\cryptography-1.0.2-py2.7-win32.egg
C:\Anaconda2\lib\site-packages\win32
C:\Anaconda2\lib\site-packages\win32\lib
C:\Anaconda2\lib\site-packages\Pythonwin
C:\Anaconda2\lib\site-packages\wx-3.0-msw
loading pickled environment… not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 102 source files that are out of date
updating environment: 102 added, 0 changed, 0 removed
reading sources… [100%] ref/refs
looking for now-outdated files… none found
pickling environment… done
checking consistency… done
preparing documents… done
writing output… [100%] ref/refs
generating indices… genindex py-modindex
writing additional pages… search
copying images… [100%] model\img/fractal_core_shell_autogenfig.png ls_autogenfig.png
copying static files… done
copying extra files… done
dumping search index in English (code: en) … done
dumping object inventory… done
build succeeded.
ECHO is off.
"Build finished. The HTML pages are in _build/html."

[smk78]

NOTE: to build the all-in-one pdf you need to have TeX installed (to get pdflatex)!

[smk78]

Integrated Sasmodels and SasView documentation is now building by:

• first building the Sasmodels documentation (to allow genmodel/gentoc to trawl all the Sasmodels .py files and extract the doc strings into .rst files);
• then copying those .rst files (and associated image files) to the SasView /doc folder;
• then building the SasView documentation.

Ultimately the first two steps should be replaced by a modified genmodel/gentoc procedure within SasView. Also see #545.
The SasView 3.x.x documentation (.rst & images) has been moved to /olddocs subfolders to make way for the new SasView 4.x.x (ie, Sasmodels) documentation.

[smk78]

• The documentation for 3.x.x and 4.x.x are both available from the User Documentation help pages.
• Some 'tidying up' of the User Documentaton tocs has also taken place.
• The 'version' string of the documentation has been changed to 4.0.0-alpha.
• A way has been found to link the tutorial pdf from the documentation!!**

[smk78]

build_sphinx is now updated with an on-the-fly path replacement for the sasmodels tocs generated by gentoc. This means models can be added/removed, and their names changed, IN SASMODELS with impunity and the integrated docs build will handle the changes without manual intervention.

[smk78]

Following today's shenanigans the integrated docs build is now working again!

All dependency on the sasview\src\sas\models folder has been removed and it has been deleted.

The sasmodels docs alone continue to build without errors.

The integrated docs however are throwing 5 issues:

1)
C:\Code\sasview-local-trunk\build\lib.win32-2.7\sas\sascalc\calculator\BaseComponent?.py:docstring of sas.sascalc.calculator.BaseComponent.BaseComponent.evalDistribution:14: WARNING: Literal block ends without a blank line; unexpected unindent.

2)
C:\Code\sasview-local-trunk\build\lib.win32-2.7\sas\sascalc\calculator\BaseComponent?.py:docstring of sas.sascalc.calculator.BaseComponent.BaseComponent.evalDistribution:31: WARNING: Literal block ends without a blank line; unexpected unindent.

3)
C:\Code\sasview-local-trunk\build\lib.win32-2.7\sas\sasgui\guiframe\data_processor.py:docstring of sas.sasgui.guiframe.data_processor:14: ERROR: Unexpected indentation.

4)
C:\Code\sasview-local-trunk\docs\sphinx-docs\source\dev\api\sas.sasview.rst:116: WARNING: autodoc: failed to import module u'sas.sasview.setup_exe'; the following exception was raised:
Traceback (most recent call last):

File "C:\Anaconda2\lib\site-packages\Sphinx-1.3.1-py2.7.egg\sphinx\ext\autodoc.py", line 385, in import_object

import(self.modname)

File "C:\Code\sasview-local-trunk\build\lib.win32-2.7\sas\sasview\setup_exe.py", line 21, in <module>

raise RuntimeError("Must run setup_exe from the sasview directory")

RuntimeError: Must run setup_exe from the sasview directory

5)
C:\Code\sasview-local-trunk\docs\sphinx-docs\source\dev\api\sas.sasview.rst:124: WARNING: autodoc: failed to import module u'sas.sasview.setup_mac'; the following exception was raised:
Traceback (most recent call last):

File "C:\Anaconda2\lib\site-packages\Sphinx-1.3.1-py2.7.egg\sphinx\ext\autodoc.py", line 385, in import_object

import(self.modname)

File "C:\Code\sasview-local-trunk\build\lib.win32-2.7\sas\sasview\setup_mac.py", line 43, in <module>

import sas.models as models

ImportError: No module named models

I haven't thus far been able to see where they are coming from. Help welcome!

[butler]

First items I think are fixed (Note directive now works properly). The last two I don't think get "fixed" they are what they say — they don't work unless running from the exe evironment. They should probably be excluded from the docs build? At any rate they do not seem to affect the documentation output in any way.

data_processor on the other hand is the one py file with a doc string containing a reference to a figure which is not properly being sucked in. It was in the old docs so probably a path issue of some kind — still to work on, but the docs build (just a broken image icon in the dev docs at the point where that figure should be.

[butler]

data_processor now fixed… at least for loading figure. SMK should check again.

[smk78]

19:30 GMT
Have just checked sasmodels and integrated sasview docs build at PaulB's request. Used Sphinx 1.3.6.

Issues 4) & 5) above still exist.

Just one (irritating) undefined label warning to mag_help in core_multi_shell is left. I think it is because mag_help is in a different folder when the docs get built so the :ref: can't find it but I haven't thus far found a path string that includes it…

But I have also just noticed that fitting_help, for example, (see the batch fit section) is not finding:

• gen_gui_help.bmp
• mag_vector.bmp
• mag_vector.bmp
• new_model.bmp
• plot_button.bmp
• view_button.bmp

when the page renders.

[butler]

actually the bmp files are found no problem. The issue is that somewhere along the way those files became corrupt - Loading with a simple image viewer gives the message that they are corrupt. Need to find the original files … probably can find on github at some previous revision.

ref I think is not done right … but need to look into that more.

[smk78]

Have committed 'working' versions of the .bmp files. Images in fitting_help now render ok.

[smk78]

With the exception of the setup_exe and setup_mac warnings, and the problematic undefined label, (see above) the integrated docs seem fine now.

[butler]

broken link is now fixed … temporarily — sasmodels cannot be linking to SasView documentation in the long run since SasView depends on sasmodels not the other way round and others may also depend on sasmodels. Have created ticket to that effect for next release+1. Also have added a ticket to cleanu up a bunch of stuff in build_sphinx.py. The exe and mac scrapes should be fixed as part of that (i.e. we should not be scraping those files!).

I think this ticket can now be closed.

[smk78]

Sasmodels build warning has now changed to:

E:\SasViewDevelopment?\sasmodels\doc\model\core_multi_shell.rst:123: WARNING: unknown document: ../sasgui/perspectives/fitting/mag_help

but the integrated build now resolves this.

I am closing the ticket.