Tweet
Tweet

Slide 1

Slide 1 text

Building Open-Source Tools via GitHub VERA Talk November 13, 2019 Adina Feinstein !1

Slide 2

Slide 2 text

Outline 1. Setting up a GitHub respository 2. Accessing your repository locally 3. Creating basic documentation 4. Creating Build the Docs 5. Using PyPI 6. Package basics !2

Slide 3

Slide 3 text

1. Setting up a GitHub respository 2. Accessing your repository locally 3. Creating basic documentation 4. Creating Build the Docs 5. Using PyPI 6. Package basics Outline !3

Slide 4

Slide 4 text

1. Setting up a GitHub repository !4

Slide 5

Slide 5 text

1. Setting up a GitHub repository !4

Slide 6

Slide 6 text

1. Setting up a GitHub repository !5

Slide 7

Slide 7 text

1. Setting up a GitHub repository !5

Slide 8

Slide 8 text

1. Setting up a GitHub respository 2. Accessing your repository locally 3. Creating basic documentation 4. Creating Build the Docs 5. Using PyPI 6. Package basics Outline !6

Slide 9

Slide 9 text

2. Accessing your repository locally There are two ways to get your repository on your machine: 1. You can use git clone $ git clone username@host:/path/to/repository !7

Slide 10

Slide 10 text

2a. Using the Git commands !8

Slide 11

Slide 11 text

2a. Using the Git commands !8

Slide 12

Slide 12 text

2a. Using the Git commands !8

Slide 13

Slide 13 text

The shortcuts you need to know 1. Proposing changes to given file(s) $ git add 2. Committing your changes to the repository $ git commit -m “Commit message” 3. Sending your changes to your remote repository $ git push origin master 4. Checking if there are any updates to the code (should always be done before making changes or else you might have to deal with merge conflicts!) $ git pull 2a. Using the Git commands: Basics !9

Slide 14

Slide 14 text

The shortcuts you need to know 1. Proposing changes to given file(s) $ git add 2. Committing your changes to the repository $ git commit -m “Commit message” 3. Sending your changes to your remote repository $ git push origin master 4. Checking if there are any updates to the code (should always be done before making changes or else you might have to deal with merge conflicts!) $ git pull 2a. Using the Git commands: Basics !9

Slide 15

Slide 15 text

The shortcuts you need to know 1. Proposing changes to given file(s) $ git add 2. Committing your changes to the repository $ git commit -m “Commit message” 3. Sending your changes to your remote repository $ git push origin master 4. Checking if there are any updates to the code (should always be done before making changes or else you might have to deal with merge conflicts!) $ git pull 2a. Using the Git commands: Basics !9

Slide 16

Slide 16 text

The shortcuts you need to know 1. Proposing changes to given file(s) $ git add 2. Committing your changes to the repository $ git commit -m “Commit message” 3. Sending your changes to your remote repository $ git push origin master 4. Checking if there are any updates to the code (should always be done before making changes or else you might have to deal with merge conflicts!) $ git pull 2a. Using the Git commands: Basics !9

Slide 17

Slide 17 text

The shortcuts you need to know 1. Proposing changes to given file(s) $ git add 2. Committing your changes to the repository $ git commit -m “Commit message” 3. Sending your changes to your remote repository $ git push origin master 4. Checking if there are any updates to the code (should always be done before making changes or else you might have to deal with merge conflicts!) $ git pull 2a. Using the Git commands: Basics !9

Slide 18

Slide 18 text

If you’re updating software that other people use, it is recommended to make changes in a new branch and then merge branches. 1. Creating a new branch $ git checkout -b 2. Pushing the branch to GitHub $ git push origin 3. Switching to a branch that was created on GitHub $ git checkout 2a. Using the Git commands: Branches !10

Slide 19

Slide 19 text

If you’re updating software that other people use, it is recommended to make changes in a new branch and then merge branches. 1. Creating a new branch $ git checkout -b 2. Pushing the branch to GitHub $ git push origin 3. Switching to a branch that was created on GitHub $ git checkout 2a. Using the Git commands: Branches !10

Slide 20

Slide 20 text

If you’re updating software that other people use, it is recommended to make changes in a new branch and then merge branches. 1. Creating a new branch $ git checkout -b 2. Pushing the branch to GitHub $ git push origin 3. Switching to a branch that was created on GitHub $ git checkout 2a. Using the Git commands: Branches !10

Slide 21

Slide 21 text

If you’re updating software that other people use, it is recommended to make changes in a new branch and then merge branches. 1. Creating a new branch $ git checkout -b 2. Pushing the branch to GitHub $ git push origin 3. Switching to a branch that was created on GitHub $ git checkout 2a. Using the Git commands: Branches !10

Slide 22

Slide 22 text

There are two ways to get your repository on your machine: 2. You can download the GitHub desktop app (for macOS & Windows) https://desktop.github.com/ 2. Accessing your repository locally !11

Slide 23

Slide 23 text

2b. Cloning from the GitHub app !12

Slide 24

Slide 24 text

2b. Cloning from the GitHub app !12

Slide 25

Slide 25 text

2b. Cloning from the GitHub app !12

Slide 26

Slide 26 text

2b. Cloning from the GitHub app !12

Slide 27

Slide 27 text

2b. Cloning from the GitHub app !12

Slide 28

Slide 28 text

2b. Using the Git app: Basics !13

Slide 29

Slide 29 text

2b. Using the Git app: Basics “git add” !13

Slide 30

Slide 30 text

2b. Using the Git app: Basics “git add” “git commit” !13

Slide 31

Slide 31 text

2b. Using the Git app: Basics “git add” “git commit” !13

Slide 32

Slide 32 text

2b. Using the Git app: Basics “git add” “git commit” “git push” !13

Slide 33

Slide 33 text

2b. Using the Git app: Branches !14

Slide 34

Slide 34 text

2b. Using the Git app: Branches !14

Slide 35

Slide 35 text

2b. Using the Git app: Branches !14

Slide 36

Slide 36 text

2b. Using the Git app: Branches !14

Slide 37

Slide 37 text

2b. Using the Git app: Branches !14

Slide 38

Slide 38 text

1. Setting up a GitHub respository 2. Accessing your repository locally 3. Creating basic documentation 4. Creating Build the Docs 5. Using PyPI 6. Package basics Outline !15

Slide 39

Slide 39 text

!16 3. Creating basic documentation

Slide 40

Slide 40 text

!16 3. Creating basic documentation

Slide 41

Slide 41 text

!16 3. Creating basic documentation README.md is written in Markdown (kind of similar to HTML)

Slide 42

Slide 42 text

!17 3. Creating basic documentation

Slide 43

Slide 43 text

!17 3. Creating basic documentation You can create fancier docs with Read the Docs!

Slide 44

Slide 44 text

1. Setting up a GitHub respository 2. Accessing your repository locally 3. Creating basic documentation 4. Creating Build the Docs 5. Using PyPI 6. Package basics Outline !18

Slide 45

Slide 45 text

!19 4. Using Read the Docs Read the Docs & Sphinx are documentation generating softwares that make it easy to keep your documentation up-to-date. In order to use the software, you must create a Read the Docs account and link it to your GitHub page: https://readthedocs.org/dashboard/ After importing your repository you will get a https://xx.readthedocs.io website.

Slide 46

Slide 46 text

!20 4. Using Read the Docs In order to use Sphinx to then build your documentation, you need a directory in your GitHub repository called docs and within docs you simply run the command $ sphinx-quickstart To see what your documentation looks like, you can run $ make html

Slide 47

Slide 47 text

!21 4a. Proper documentation format Sphinx reads in a very specific format for your documentation.

Slide 48

Slide 48 text

!21 4a. Proper documentation format Sphinx reads in a very specific format for your documentation. class Source(object): ”””A single source observed by TESS. Parameters ---------- tic : int, optional The TIC ID of the source. gaia : int, optional The GAIA DR2 source_id. coords : tuple, astropy.coordinates.SkyCoord The (RA, Dec) coords of the obj. Attributes ---------- tess_mag : float The TESS magnitude from the TIC. “”” def __init__(self, tic=None, gaia=None, coords=None): self.tic = tic self.gaia = gaia self.coords = coords

Slide 49

Slide 49 text

!21 4a. Proper documentation format Sphinx reads in a very specific format for your documentation. class Source(object): ”””A single source observed by TESS. Parameters ---------- tic : int, optional The TIC ID of the source. gaia : int, optional The GAIA DR2 source_id. coords : tuple, astropy.coordinates.SkyCoord The (RA, Dec) coords of the obj. Attributes ---------- tess_mag : float The TESS magnitude from the TIC. “”” def __init__(self, tic=None, gaia=None, coords=None): self.tic = tic self.gaia = gaia self.coords = coords )

Slide 50

Slide 50 text

!22 4b. Setting up tabs: API Your api.rst file allows your comments to be built to to the website. These should include all of the classes in your package.

Slide 51

Slide 51 text

!23 4b. Setting up tabs: Homepage Your index.rst file will serve as the homepage to your website.

Slide 52

Slide 52 text

!23 4b. Setting up tabs: Homepage Your index.rst file will serve as the homepage to your website.

Slide 53

Slide 53 text

!23 4b. Setting up tabs: Homepage Your index.rst file will serve as the homepage to your website.

Slide 54

Slide 54 text

!23 4b. Setting up tabs: Homepage Your index.rst file will serve as the homepage to your website.

Slide 55

Slide 55 text

!23 4b. Setting up tabs: Homepage Your index.rst file will serve as the homepage to your website.

Slide 56

Slide 56 text

!24 4b. Setting up tabs: getting_started package/docs/getting_started will host additional documentation and tutorial Jupyter notebooks. Each tab is a different .rst or .ipynb file.

Slide 57

Slide 57 text

!25 4b. Setting up tabs: Useful formatting guide 1. Creating headers ============= 2. Creating subheaders ------------------------ 3. Bullet points that are highlighted blue * 4. Tabbing for inline code tab + 5 spaces

Slide 58

Slide 58 text

!25 4b. Setting up tabs: Useful formatting guide 1. Creating headers ============= 2. Creating subheaders ------------------------ 3. Bullet points that are highlighted blue * 4. Tabbing for inline code tab + 5 spaces

Slide 59

Slide 59 text

!25 4b. Setting up tabs: Useful formatting guide 1. Creating headers ============= 2. Creating subheaders ------------------------ 3. Bullet points that are highlighted blue * 4. Tabbing for inline code tab + 5 spaces

Slide 60

Slide 60 text

!25 4b. Setting up tabs: Useful formatting guide 1. Creating headers ============= 2. Creating subheaders ------------------------ 3. Bullet points that are highlighted blue * 4. Tabbing for inline code tab + 5 spaces

Slide 61

Slide 61 text

!26 4b. Setting up tabs: Index Your index.rst file will also be where you build your index.

Slide 62

Slide 62 text

!27 4c. Travis CI

Slide 63

Slide 63 text

!27 4c. Travis CI You can also set up automatic tests which run with every GitHub push!

Slide 64

Slide 64 text

!28 4c. Travis CI Travis CI depends on test files that are located in ///tests You should have tests for every class in your package. With every GitHub push, Travis will build package and run all of your tests. The progress can be tracked on https://travis-ci.org You have to make an account with Travis CI and link it to your GitHub.

Slide 65

Slide 65 text

!29 4d. Linking docs to a personal website Your docs should be copied to a new branch called something like gh-pages

Slide 66

Slide 66 text

!29 4d. Linking docs to a personal website Your docs should be copied to a new branch called something like gh-pages

Slide 67

Slide 67 text

!29 4d. Linking docs to a personal website

Slide 68

Slide 68 text

!29 4d. Linking docs to a personal website

Slide 69

Slide 69 text

!29 4d. Linking docs to a personal website

Slide 70

Slide 70 text

1. Setting up a GitHub respository 2. Accessing your repository locally 3. Creating basic documentation 4. Creating Build the Docs 5. Using PyPI 6. Package basics Outline !30

Slide 71

Slide 71 text

!31 5. PyPI: Making packages easy to install You know when you want to download a new package and you do pip install ? This is how to make your code do that! PyPI = Python Package Index https://pypi.org You have to register for an account to get a PyPI package name.

Slide 72

Slide 72 text

!31 5. PyPI: Making packages easy to install You know when you want to download a new package and you do pip install ? This is how to make your code do that! PyPI = Python Package Index https://pypi.org You have to register for an account to get a PyPI package name.

Slide 73

Slide 73 text

!31 5. PyPI: Making packages easy to install You know when you want to download a new package and you do pip install ? This is how to make your code do that! PyPI = Python Package Index https://pypi.org You have to register for an account to get a PyPI package name.

Slide 74

Slide 74 text

!32 5a. Creating your setup.py file

Slide 75

Slide 75 text

!32 5a. Creating your setup.py file The name of the directory where your packaged files are

Slide 76

Slide 76 text

!32 5a. Creating your setup.py file The name of the directory where your packaged files are A description for the PyPI website

Slide 77

Slide 77 text

!32 5a. Creating your setup.py file

Slide 78

Slide 78 text

!33 5a. Creating your setup.py file

Slide 79

Slide 79 text

!33 5a. Creating your setup.py file The packages you’re creating with your setup file

Slide 80

Slide 80 text

!33 5a. Creating your setup.py file The packages you’re creating with your setup file Packages yours is dependent on and any specific versions needed

Slide 81

Slide 81 text

!34 5b. Versions Your package directory should always have a version.py file. This is all that’s in that file: __version__ = "0.0.1" It’s good practice to do a pre-release before every version update. Pre-releases can be pip installed by specifying the version number. Then, once you test everything you want, you can upload the new version for real. Pre-releases are specified by __version__ = “0.0.1rc1" Version numbers have to be unique and always increasing!

Slide 82

Slide 82 text

!35 5c. Uploading to PyPI You need to install twine to upload first python -m pip install —user —upgrade twine To setup, you’ll need to login to your PyPI account python twine —repository-url https://test.pypi.org/legacy/ dist/* From there, every update is simple: python setup.py sdist python setup.py sdist —upload

Slide 83

Slide 83 text

!35 5c. Uploading to PyPI You need to install twine to upload first python -m pip install —user —upgrade twine To setup, you’ll need to login to your PyPI account python twine —repository-url https://test.pypi.org/legacy/ dist/* From there, every update is simple: python setup.py sdist python setup.py sdist —upload

Slide 84

Slide 84 text

!35 5c. Uploading to PyPI You need to install twine to upload first python -m pip install —user —upgrade twine To setup, you’ll need to login to your PyPI account python twine —repository-url https://test.pypi.org/legacy/ dist/* From there, every update is simple: python setup.py sdist python setup.py sdist —upload

Slide 85

Slide 85 text

1. Setting up a GitHub respository 2. Accessing your repository locally 3. Creating basic documentation 4. Creating Build the Docs 5. Using PyPI 6. Package basics Outline !36

Slide 86

Slide 86 text

!37 6a. Files every package should have version.py This will keep track of the version you’re on. __version__ = “0.0.1” This will need to be manually updated before each PyPI update.

Slide 87

Slide 87 text

!38 6a. Files every package should have __init__.py This will load in all of your classes to be easily called import os PACKAGEDIR = os.path.abspath(os.path.dirname(__file__)) from .version import __version__ from .targetdata import * from .source import *

Slide 88

Slide 88 text

!38 6a. Files every package should have __init__.py This will load in all of your classes to be easily called import os PACKAGEDIR = os.path.abspath(os.path.dirname(__file__)) from .version import __version__ from .targetdata import * from .source import *

Slide 89

Slide 89 text

!39 6a. Files every package should have from .source import *

Slide 90

Slide 90 text

!39 6a. Files every package should have from .source import * Imports package path

Slide 91

Slide 91 text

!39 6a. Files every package should have from .source import * Imports package path Imports classes/functions from other files in

Slide 92

Slide 92 text

!39 6a. Files every package should have from .source import * Imports package path Imports classes/functions from other files in Identifies classes/ functions to import in *