Project baja Documentation¶

Website links¶

• https://github.com/
• The Pro Git book is available here!

Useful Commands¶

add everything to the commit (including new file and files that were deleted):

git add -A

commit all of the changes:

git commit -m "some message about what you did"

push to remote account:

git push origin master

view current tags:

git tag

making a new tag:

git tag -a V0.0.1 -m " new version 0.0.1"

committing a tag:

git push origin master --tags

checkout a tag:

git checkout -b [branchname] [tagname]

see which branch you are on:

git branch

connecting to github:

git remote add origin git@github.com:username/new_repo

• making a branch look here

Then make a new repository using the interweb

• Check out this link for more info.

Caching your github password:

git config --global credential.helper 'cache --timeout=3600'
# Set the cache to timeout after 1 hour (setting is in seconds)

Another way to connect to github it using ssh¶

Initially the error was:

febbo@febbo-HP-ZBook-17-G2:~/.julia/v0.5/VehicleModels$ git push origin master
Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

• This was obtained when initially setting up the git repositories in julia after cloning a package and trying to push modifications back up to the remote repository.

• Information on this can be founds at , or by following the two steps a fix may be obtained:

  1. Make an ssh key and add it to github, following.
  2. Check out this, or use the following commands:

  • A program to hold private keys for public authentication.

    type:

    ssh-agent
    

  • Initially the agent does not hold any private keys.

    So run:

    ssh-add
    

Mistakes I Made¶

• Make sure that you are working on the master branch!

  • Do not check out a tag and start making changes only to realize that you are not on the master branch!

• Trying to connect to github using ssh

  1. Create a github repository, with the name ( for example: huckl3b3rry87/LiDAR.jl )
  2. Then

  Type this in the terminal:

  febbo@febbo-HP-ZBook-17-G2:~/.julia/v0.5/LiDAR$ git remote add origin git@github.com:huckl3b3rry87/LiDAR.jl
  

  3. Then

  Try this:

  febbo@febbo-HP-ZBook-17-G2:~/.julia/v0.5/LiDAR$ git pull master
  

  4. Next

  Get this:

  fatal: 'master' does not appear to be a git repository
  fatal: Could not read from remote repository.
  
  Please make sure you have the correct access rights
  and the repository exists.
  

  Next we are going to test the ssh connection

  5) Attempt to ssh to GitHub By typing:

  febbo@febbo-HP-ZBook-17-G2:~/.julia/v0.5/LiDAR$ ssh -T git@github.com
  Hi huckl3b3rry87! You've successfully authenticated, but GitHub does not provide shell access.
  

  6) realize that you messed up by typing:

  git pull master
  

  and not:

  git pull origin master
  

Useful Linux Programs with julia¶

In the Linux terminal:

sudo dpkg --install atom-amd64.deb
sudo apt install ffmpeg
sudo apt-get install cmake bar time binutils make libssl-dev gfortran libunwind8-dev gcc g++ #clang curl perl wget m4 patch pkg-config
sudo apt-get install gsfonts-x11
sudo apt-get install notepadqq
sudo apt-get update
sudo apt-get install gfortran
sudo apt-get install libnlopt0
sudo apt-get install openssh-server
sudo apt install ipmiutil
sudo apt-get install hdf5-tools
apm install latex # Atom package manager for latex!
sudo apt-get install pdf2svg # for PGFPlots
pip install sphinxcontrib-bibtex

Java¶

First I tried a few things including:

sudo apt-get install default-jre
sudo apt-get update

And:

sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-7-jre

This messed stuff up and then I deleted all of my old java versions using:

sudo natilus

Ended up needing to follow this advice <http://askubuntu.com/questions/251213/unable-to-install-default-jdk >:

sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer
java -version
sudo apt-get install oracle-java8-set-default

This finally worked and I was able to run JabRef with no problem using:

java -jar JabRef-3.8.jar

If something is broken:

sudo apt-get -f install

Basic Linux Commands¶

Never run an executable in root!

Some more info can be found on ` this page <https://www.cyberciti.biz/faq/tar-extract-linux/>`.

To unpack a tar file:

tar -xvf file.tar

To extract a .tar.gz:

tar -xzvf file.tar.gz

Unzip:

unzip stuff.zip -d /destination/folder

directory comment:

$HOME = /home/febbo

Run a jar file: java -jar lad

Issues and Fixes¶

1. Trying to uninstall sphinx so that I could get a newer version without bugs:

febbo@febbo-HP-ZBook-17-G2:~/Desktop/useful downloads$ pip uninstall sphinx
Cannot remove entries from nonexistent file /home/febbo/anaconda3/lib/python3.5/site-packages/easy-install.pth

The problem: This probably won’t work:

conda update setuptools

The fix, was to download ez_setup.py from this link and run it in the terminal:

febbo@febbo-HP-ZBook-17-G2:~$ python ez_setup.py

Then I could uninstall Sphinx-1.4.1:

febbo@febbo-HP-ZBook-17-G2:~$ pip uninstall sphinx
Uninstalling Sphinx-1.4.1:
/home/febbo/anaconda3/bin/sphinx-apidoc
/home/febbo/anaconda3/bin/sphinx-autogen
/home/febbo/anaconda3/bin/sphinx-build
/home/febbo/anaconda3/bin/sphinx-quickstart
/home/febbo/anaconda3/lib/python3.5/site-packages/Sphinx-1.4.1-py3.5.egg
Proceed (y/n)? y
Successfully uninstalled Sphinx-1.4.1

There was reason I needed to uninstall this version of Sphinx was because the citations where not working.

Finally I installed Sphinx-1.5.2:

#Install from newest dev version in stable branch::
pip install git+https://github.com/sphinx-doc/sphinx@stable

Atom¶

Atom Flight Manual

Useful things:

spell check <https://github.com/atom/spell-check>:

ctrl+shift+;

Markdown Preview Package:

ctr+shift+m

https://github.com/atom/markdown-preview

Subscripts:

variable\_1+tab

Using \(/LaTeX\) with Atom. It was suggested to use Tex Live <https://www.tug.org/texlive/acquire-netinstall.html> Where the quick install instructions are here<https://www.tug.org/texlive/quickinstall.html> https://atom.io/packages/latex

TeX Live¶

I use this with Atom.

https://www.tug.org/texlive/ https://atom.io/packages/latex

After installing TeX Live: * Add /usr/local/texlive/2016/texmf-dist/doc/info to INFOPATH. * Add /usr/local/texlive/2016/texmf-dist/doc/man to MANPATH (if not dynamically found). * Most importantly, add /usr/local/texlive/2016/bin/x86_64-linux to your PATH for current and future sessions.

To do this change the bashrc file:

gksu gedit /etc/bash.bashrc

Paste this at the end:

PATH=/usr/local/texlive/2016/bin/x86_64-linux:$PATH; export PATH # make sure that there are NO spaces
MANPATH=/usr/local/texlive/2016/texmf-dist/doc/man:$MANPATH; export MANPATH
INFOPATH=/usr/local/texlive/2016/texmf-dist/doc/info:$INFOPATH; export INFOPATH

Then in Atom, go to settings and add the path to the texlive:

/usr/local/texlive/2016/bin/x86_64-linux

Potential Issues¶

• If the julia binary is not where it belongs ( for instance I put it in my /opt/... folder)

  • Change the julia .config file (in Atom) to the proper folder (where julia binaries are)

• Otherwise

  • leave it as : juliaPath: “julia”

I had to:

Pkg.clone("https://github.com/JunoLab/Juno.jl")
Pkg.update()

Make sure you close both atom and julia after installation. Now you should be able to run julia from Atom!

Sphinx¶

1. Installation

Or in the terminal run:

pip install sphinx

1.b. Uninstall

2. Getting Started

   • an awesome video introduction

   • toctree

   • basic commands and syntax

   • useful resource

   • Common commands:

     • To start documenting:

       sphinx-quickstart
       

     • To manually build documentation:

       make html
       

     • To clean out an old build folder when things have changed significantly:

       make clean
       

     • changing the themes

       In conf.py change:

       html_theme = 'haiku'
       

       Or a my main one:

       import sphinx_rtd_theme
       html_theme = "sphinx_rtd_theme"
       html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
       

       • here is an awesome theme

3. Some issues that I ran into:

• Make sure that the “toctree” is indented by 3 space characters. I listed the .rst files by 4 space characters and this created an issue. To resolve the issue, you need to have the same indentation level.

• When cross referencing things in the document make sure you skip a space when you define the ref.

  • like this

  works:

  .. _ploy_div:
  
  Polynomial Division
  -------------------
  

  • not like this

  fails:

  .. _ploy_div:
  Polynomial Division
  -------------------
  

4. Setting up a server to build the documentation when a change is detected.

Installation:

pip install sphinx-autobuild

Then go into your main directory and type:

sphinx-autobuild docs docs/_build/html

Or the directory that contains conf.py and type:

sphinx-autobuild . _build_html

Then visit the website: http://127.0.0.1:8000/

• This will show you the live changes (after each save!!)

More information can be found using this resource.

Read The Docs¶

Read the Docs is useful resource to host the webpage.

Some Issues:

• The git repository for OCP is private and this website only hosts public repositories.
• Had to remove the last line here in conf.py for the code to work with ReadtheDocs.

like this:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinxcontrib.bibtex',
]
#    'sphinx.ext.githubpages',

• Had to make sure that the name of the project was correct
• Had to make sure that the webhook was activated on github

MkDocs¶

Another nice looking tool is MkDocs.

Documentor.jl¶

Another nice looking tool is here.

Using Sphinx BibTex extension¶

Sphinx BibTex extension

• To install

Do this:

 pip install sphinxcontrib-bibtex

 In ``conf.py`` add:
 ::

   extensions = ['sphinxcontrib.bibtex']

* MAKE SURE * that it is *added* to the rest of extensions!! Not just at the top, it will be removed!!!Ahh

Like this:

::

  extensions = [
      'sphinx.ext.autodoc',
      'sphinx.ext.doctest',
      'sphinx.ext.intersphinx',
      'sphinx.ext.todo',
      'sphinx.ext.coverage',
      'sphinx.ext.mathjax',
      'sphinx.ext.ifconfig',
      'sphinxcontrib.bibtex',
      ]

Also, you can avoid these errors on readthedocs.com:

python /home/docs/checkouts/readthedocs.org/user_builds/nloptcontroljl/envs/latest/bin/pip install --exists-action=w --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/nloptcontroljl/.cache/pip -rpip install sphinxcontrib-bibtex
Could not open requirements file: [Errno 2] No such file or directory: 'pip install sphinxcontrib-bibtex'
You are using pip version 8.1.2, however version 9.0.1 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.
Command time: 0s Return: 1

By typing:

requirements.txt

Into the Advanced Settings Page and making a requirements.txt file with:

pip install --upgrade pip
pip install sphinxcontrib-bibtex

More on this is here <https://github.com/huckl3b3rry87/NLOptControl.jl/issues/2#issuecomment-268052941>

Example: To cite:

according to :cite:`someone` yada yada..

Then, at the end of the document include:

.. bibliography:: references.bib

JabRef¶

BibTex files can be managed with a free software called JabRef

EndNote¶

I still use this tool, but it costs money and I do not have it on Ubuntu.

Stackoverflow¶

A more general venue for asking questions to the online community of experts in various feilds.

GitHub¶

If you have issues with peoples software, you can submit an issue.

Gitter¶

Basicaly an instant message service for developers. I have used it for julia, plots.jl, and juno.jl.