Documentation

[pedromorgan]

What is the current technique used for generating the documentation at http://pythonhosted.org//geotecha/

Want to contribute to the docs, and build them as am good at that..

[pedromorgan]

I get the fact its its sphinx, and that leads to problem of knocking out documentation on a machine with all libs installed,
and read the docs etc.. which cannot import "some libs"

Am thinking of setting up a server to compile stuff and upload, as part of the open-geotechnical project which is all sphinx..

[rtrwalker]

Taking a closer look I can see how building the docs can be confusing... or even impossible with the info that I've given! It is a little bit convoluted and I did it a while ago but having dug up some old notes here goes...

Firstly on the python package index page for geotecha https://pypi.python.org/pypi/geotecha/0.1.4#building-the-docs I simply say "The geotecha docs can be build by running the following in the docs directory:"
make html
While this is true, I just realised that I never actually include the "docs" folder in the source distribution on the pypi page! In order to get the docs directory you will have to make a clone or copy the geotecha github repository. You can see the docs folder at https://github.com/rtrwalker/geotecha .

Within the docs folder read the readme.txt and create the symlink to the examples folder. (I've only ever done this on windows so have no idea how it would work on other systems). If the symlink already exists from the github clone/download, then I would delete it and create it again.

I think you actually have to have geotecha installed because the sphinxext either uses some geotecha functionality, makes a directory of all the modules from the installed package, or both. Note I have tried building geotecha itself on python3.5 and python 3.6 but have so far failed so I'm sticking with python 3.4 for the moment (I have a py34 anaconda env). FYI on python 3.4 I've found it easiest to build geotecha after installing mingwpy (currently only working on python3.4 but apparently the way of the future of building fortran etc. extensions such as I have in geotecha; see few minutes of this Steve Dower PyCon2017 talk ) with the following run in the 'geotecha' folder containing setup.py:

python -m pip install -U pip setuptools
pip install -i https://pypi.anaconda.org/carlkl/simple mingwpy
python setup.py install --compiler=mingw32

OK now back to the docs. Delete the "docs_build" directory if it exists. Open the docs\api folder and delete everything in it (should just be rst files). These last steps are not strictly necessary but make for a clean build from scratch.

Open a cmd prompt (again I've only done this on windows). In the docs folder containing make.bat use:
make html

You should now have a local copy of the html documentation in the _build directory. Open the geotecha\docs_build\html\index.html file to check.

The real magic happens in the sphinxext py files for which I've long forgotten exactly what I did. A lot of adapting/copying from the matplotlib documentation I seem to remember. You will probably have to wade through them if you really want to know what is happening. I think docs_static\default.css is straight from matplotlib (at some point in the past???). Look for any rst file with an old modified/created date; these are likely hardcoded with all others generated through the sphinxext. Teh might be some customoisation of the docs\conf.py file. There are some python scripts in the geotecha\tools folder that do some doc operations manually.

As for getting the docs (and the package itself) on pypi...

In home directory create ".pyrc" file. (In windows name it ".pyrc." and the last "." will be removed.)
The .pypirc file should be like:

index-servers=
    pypi
    test

[test]
repository = https://testpypi.python.org/pypi
username = rohan
password = xxxx
[pypi]
repository = https://pypi.python.org/pypi
username = rohan
password = xxxx

-note that if the password lines are missing, you will be prompted to enter one. However this will then throw an error. http://bugs.python.org/issue18454 . So basically you need the password in there.

Now you need to register your package and upload to the test pypi site (run all this in the geotecha directory containing setup.py):

python setup.py register -r https://testpypi.python.org/pypi
python setup.py sdist upload -r https://testpypi.python.org/pypi
python setup.py bdist upload -r https://testpypi.python.org/pypi
python setup.py bdist_egg upload -r https://testpypi.python.org/pypi
python setup.py bdist_wininst upload -r https://testpypi.python.org/pypi

Test that pip can find the package by installing from pipy:
pip install -i https://testpypi.python.org/pypi geotecha
In anaconda3\envs\py34\Lib\site-packages I get geotecha folder, geotecha egg folder.

Uploading docs to pypi (note the workarounds might not be needed any more???). We will upload to testpypi first to see if anything goes wrong.

1. Install sphinx-pypi_upload
   pip install sphinx-pypi-upload
2. I get the error "error: no files found in upload directory 'docs/build/html'" or something. Based on website: https://bitbucket.org/jezdez/sphinx-pypi-upload/issue/2/upload-fails-when-directory-has-no-files
3. Replace sphinx_pypi_upload.py in site-packages with newer version of 'sphinx_pypi_upload.py'. If you can't find "sphinx_pypi_upload.py" in site-packages then it is probably in an egg named "Sphinx_PyPI_upload-0.2.1-py2.7.egg" or something. Open the egg in 7zip and 1)delete the pyc file 2) replace the 'sphinx_pypi_upload.py' file.
4. Build sphinx docs with the following (I think my normal "make html in the docs directroy is fine").
   python setup.py build_sphinx --source-dir=docs/ --build-dir=docs/_build --all-files
5. Upload to pypi with
   python setup.py upload_sphinx -r https://testpypi.python.org/pypi --upload-dir=docs/_build/html

I made a bat file upload_to_pypi.bat with the following commands (note this assumes py27 and py34 environments from

Anaconda/conda):
C:\Anaconda3\envs\py27\python.exe setup.py register -r https://testpypi.python.org/pypi
C:\Anaconda3\envs\py27\python.exe setup.py sdist upload -r https://testpypi.python.org/pypi
C:\Anaconda3\envs\py27\python.exe setup.py bdist_egg upload -r https://testpypi.python.org/pypi
C:\Anaconda3\envs\py27\python.exe setup.py bdist_wininst upload -r https://testpypi.python.org/pypi
C:\Anaconda3\envs\py27\python.exe setup.py upload_sphinx -r https://testpypi.python.org/pypi --upload-dir=docs/_build/html
C:\Anaconda3\envs\py34\python.exe setup.py bdist_egg upload -r https://testpypi.python.org/pypi
C:\Anaconda3\envs\py34\python.exe setup.py bdist_wininst upload -r https://testpypi.python.org/pypi

When ready remove the "test" from all references to testpypi and repeat the above commands for real!

Useful links:
https://wiki.python.org/moin/TestPyPI
http://jamie.curle.io/blog/my-first-experience-adding-package-pypi/
https://pypi.python.org/pypi/Sphinx-PyPI-upload/0.2.1
https://pythonhosted.org/an_example_pypi_project/buildanduploadsphinx.html
https://pythonhosted.org/an_example_pypi_project/setuptools.html

[pedromorgan]

umm.. ok captain, message recieved,,
not understodd yet.. but will report back..

Its easier than u think it is..
am starting #1 on nix another way ;-))

[rtrwalker]

I threw everything in for my own records as much as anything else. It boils down to 1. install geotecha, 2. run make html in the docs directory of the github repository, 3. upload to pipy.