├── .gitignore ├── Makefile ├── README.md ├── book-plan.png ├── book-plan.xmind ├── make.bat └── source ├── about.rst ├── conf.py ├── doc.rst ├── examples ├── go │ ├── hello_deps │ │ └── src │ │ │ └── github.com │ │ │ └── jmcvetta │ │ │ └── hello │ │ │ ├── greeter │ │ │ └── greeter.go │ │ │ └── hello.go │ └── src │ │ └── hello │ │ └── hello.go └── python │ └── hello │ └── hello.py ├── godoc.time.now.txt ├── hello.rst ├── images └── godoc-mgo │ ├── collection.png │ ├── index.png │ ├── package.png │ ├── search.png │ └── src-count.png ├── index.rst ├── intro.rst ├── layout.rst ├── setup.rst └── toolchain.rst /.gitignore: -------------------------------------------------------------------------------- 1 | *.py[cod] 2 | 3 | # C extensions 4 | *.so 5 | 6 | # Packages 7 | *.egg 8 | *.egg-info 9 | dist 10 | build 11 | eggs 12 | parts 13 | bin 14 | var 15 | sdist 16 | develop-eggs 17 | .installed.cfg 18 | lib 19 | lib64 20 | 21 | # Installer logs 22 | pip-log.txt 23 | 24 | # Unit test / coverage reports 25 | .coverage 26 | .tox 27 | nosetests.xml 28 | 29 | # Translations 30 | *.mo 31 | 32 | # Mr Developer 33 | .mr.developer.cfg 34 | .project 35 | .pydevproject 36 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = build 9 | 10 | # User-friendly check for sphinx-build 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) 13 | endif 14 | 15 | # Internal variables. 16 | PAPEROPT_a4 = -D latex_paper_size=a4 17 | PAPEROPT_letter = -D latex_paper_size=letter 18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 19 | # the i18n builder cannot share the environment and doctrees with the others 20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 21 | 22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 23 | 24 | help: 25 | @echo "Please use \`make ' where is one of" 26 | @echo " html to make standalone HTML files" 27 | @echo " dirhtml to make HTML files named index.html in directories" 28 | @echo " singlehtml to make a single large HTML file" 29 | @echo " pickle to make pickle files" 30 | @echo " json to make JSON files" 31 | @echo " htmlhelp to make HTML files and a HTML help project" 32 | @echo " qthelp to make HTML files and a qthelp project" 33 | @echo " devhelp to make HTML files and a Devhelp project" 34 | @echo " epub to make an epub" 35 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 36 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 37 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 38 | @echo " text to make text files" 39 | @echo " man to make manual pages" 40 | @echo " texinfo to make Texinfo files" 41 | @echo " info to make Texinfo files and run them through makeinfo" 42 | @echo " gettext to make PO message catalogs" 43 | @echo " changes to make an overview of all changed/added/deprecated items" 44 | @echo " xml to make Docutils-native XML files" 45 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 46 | @echo " linkcheck to check all external links for integrity" 47 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 48 | 49 | clean: 50 | rm -rf $(BUILDDIR)/* 51 | 52 | html: 53 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 54 | @echo 55 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 56 | 57 | dirhtml: 58 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 59 | @echo 60 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 61 | 62 | singlehtml: 63 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 64 | @echo 65 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 66 | 67 | pickle: 68 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 69 | @echo 70 | @echo "Build finished; now you can process the pickle files." 71 | 72 | json: 73 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 74 | @echo 75 | @echo "Build finished; now you can process the JSON files." 76 | 77 | htmlhelp: 78 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 79 | @echo 80 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 81 | ".hhp project file in $(BUILDDIR)/htmlhelp." 82 | 83 | qthelp: 84 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 85 | @echo 86 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 87 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 88 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GoforPythonProgrammers.qhcp" 89 | @echo "To view the help file:" 90 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GoforPythonProgrammers.qhc" 91 | 92 | devhelp: 93 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 94 | @echo 95 | @echo "Build finished." 96 | @echo "To view the help file:" 97 | @echo "# mkdir -p $$HOME/.local/share/devhelp/GoforPythonProgrammers" 98 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GoforPythonProgrammers" 99 | @echo "# devhelp" 100 | 101 | epub: 102 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 103 | @echo 104 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 105 | 106 | latex: 107 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 108 | @echo 109 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 110 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 111 | "(use \`make latexpdf' here to do that automatically)." 112 | 113 | latexpdf: 114 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 115 | @echo "Running LaTeX files through pdflatex..." 116 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 117 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 118 | 119 | latexpdfja: 120 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 121 | @echo "Running LaTeX files through platex and dvipdfmx..." 122 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 123 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 124 | 125 | text: 126 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 127 | @echo 128 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 129 | 130 | man: 131 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 132 | @echo 133 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 134 | 135 | texinfo: 136 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 137 | @echo 138 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 139 | @echo "Run \`make' in that directory to run these through makeinfo" \ 140 | "(use \`make info' here to do that automatically)." 141 | 142 | info: 143 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 144 | @echo "Running Texinfo files through makeinfo..." 145 | make -C $(BUILDDIR)/texinfo info 146 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 147 | 148 | gettext: 149 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 150 | @echo 151 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 152 | 153 | changes: 154 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 155 | @echo 156 | @echo "The overview file is in $(BUILDDIR)/changes." 157 | 158 | linkcheck: 159 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 160 | @echo 161 | @echo "Link check complete; look for any errors in the above output " \ 162 | "or in $(BUILDDIR)/linkcheck/output.txt." 163 | 164 | doctest: 165 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 166 | @echo "Testing of doctests in the sources finished, look at the " \ 167 | "results in $(BUILDDIR)/doctest/output.txt." 168 | 169 | xml: 170 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 171 | @echo 172 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 173 | 174 | pseudoxml: 175 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 176 | @echo 177 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 178 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Go for Python Programmers 2 | ========================= 3 | 4 | This is Sphinx source code of the book [*Go for Python 5 | Programmers*](http://golang-for-python-programmers.readthedocs.org). 6 | 7 | **This book is a work in progress. It is not complete or ready for use.** 8 | 9 | 10 | ## Planning 11 | 12 | ![Book Plan](https://github.com/jmcvetta/golang-for-python-programmers/raw/master/book-plan.png "Book Plan") 13 | 14 | -------------------------------------------------------------------------------- /book-plan.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jmcvetta/golang-for-python-programmers/96389478535301014f7e921857873aeac9001726/book-plan.png -------------------------------------------------------------------------------- /book-plan.xmind: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jmcvetta/golang-for-python-programmers/96389478535301014f7e921857873aeac9001726/book-plan.xmind -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | REM Command file for Sphinx documentation 4 | 5 | if "%SPHINXBUILD%" == "" ( 6 | set SPHINXBUILD=sphinx-build 7 | ) 8 | set BUILDDIR=build 9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source 10 | set I18NSPHINXOPTS=%SPHINXOPTS% source 11 | if NOT "%PAPER%" == "" ( 12 | set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% 13 | set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% 14 | ) 15 | 16 | if "%1" == "" goto help 17 | 18 | if "%1" == "help" ( 19 | :help 20 | echo.Please use `make ^` where ^ is one of 21 | echo. html to make standalone HTML files 22 | echo. dirhtml to make HTML files named index.html in directories 23 | echo. singlehtml to make a single large HTML file 24 | echo. pickle to make pickle files 25 | echo. json to make JSON files 26 | echo. htmlhelp to make HTML files and a HTML help project 27 | echo. qthelp to make HTML files and a qthelp project 28 | echo. devhelp to make HTML files and a Devhelp project 29 | echo. epub to make an epub 30 | echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter 31 | echo. text to make text files 32 | echo. man to make manual pages 33 | echo. texinfo to make Texinfo files 34 | echo. gettext to make PO message catalogs 35 | echo. changes to make an overview over all changed/added/deprecated items 36 | echo. xml to make Docutils-native XML files 37 | echo. pseudoxml to make pseudoxml-XML files for display purposes 38 | echo. linkcheck to check all external links for integrity 39 | echo. doctest to run all doctests embedded in the documentation if enabled 40 | goto end 41 | ) 42 | 43 | if "%1" == "clean" ( 44 | for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i 45 | del /q /s %BUILDDIR%\* 46 | goto end 47 | ) 48 | 49 | 50 | %SPHINXBUILD% 2> nul 51 | if errorlevel 9009 ( 52 | echo. 53 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 54 | echo.installed, then set the SPHINXBUILD environment variable to point 55 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 56 | echo.may add the Sphinx directory to PATH. 57 | echo. 58 | echo.If you don't have Sphinx installed, grab it from 59 | echo.http://sphinx-doc.org/ 60 | exit /b 1 61 | ) 62 | 63 | if "%1" == "html" ( 64 | %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html 65 | if errorlevel 1 exit /b 1 66 | echo. 67 | echo.Build finished. The HTML pages are in %BUILDDIR%/html. 68 | goto end 69 | ) 70 | 71 | if "%1" == "dirhtml" ( 72 | %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml 73 | if errorlevel 1 exit /b 1 74 | echo. 75 | echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. 76 | goto end 77 | ) 78 | 79 | if "%1" == "singlehtml" ( 80 | %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml 81 | if errorlevel 1 exit /b 1 82 | echo. 83 | echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. 84 | goto end 85 | ) 86 | 87 | if "%1" == "pickle" ( 88 | %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle 89 | if errorlevel 1 exit /b 1 90 | echo. 91 | echo.Build finished; now you can process the pickle files. 92 | goto end 93 | ) 94 | 95 | if "%1" == "json" ( 96 | %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json 97 | if errorlevel 1 exit /b 1 98 | echo. 99 | echo.Build finished; now you can process the JSON files. 100 | goto end 101 | ) 102 | 103 | if "%1" == "htmlhelp" ( 104 | %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp 105 | if errorlevel 1 exit /b 1 106 | echo. 107 | echo.Build finished; now you can run HTML Help Workshop with the ^ 108 | .hhp project file in %BUILDDIR%/htmlhelp. 109 | goto end 110 | ) 111 | 112 | if "%1" == "qthelp" ( 113 | %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp 114 | if errorlevel 1 exit /b 1 115 | echo. 116 | echo.Build finished; now you can run "qcollectiongenerator" with the ^ 117 | .qhcp project file in %BUILDDIR%/qthelp, like this: 118 | echo.^> qcollectiongenerator %BUILDDIR%\qthelp\GoforPythonProgrammers.qhcp 119 | echo.To view the help file: 120 | echo.^> assistant -collectionFile %BUILDDIR%\qthelp\GoforPythonProgrammers.ghc 121 | goto end 122 | ) 123 | 124 | if "%1" == "devhelp" ( 125 | %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp 126 | if errorlevel 1 exit /b 1 127 | echo. 128 | echo.Build finished. 129 | goto end 130 | ) 131 | 132 | if "%1" == "epub" ( 133 | %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub 134 | if errorlevel 1 exit /b 1 135 | echo. 136 | echo.Build finished. The epub file is in %BUILDDIR%/epub. 137 | goto end 138 | ) 139 | 140 | if "%1" == "latex" ( 141 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 142 | if errorlevel 1 exit /b 1 143 | echo. 144 | echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. 145 | goto end 146 | ) 147 | 148 | if "%1" == "latexpdf" ( 149 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 150 | cd %BUILDDIR%/latex 151 | make all-pdf 152 | cd %BUILDDIR%/.. 153 | echo. 154 | echo.Build finished; the PDF files are in %BUILDDIR%/latex. 155 | goto end 156 | ) 157 | 158 | if "%1" == "latexpdfja" ( 159 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex 160 | cd %BUILDDIR%/latex 161 | make all-pdf-ja 162 | cd %BUILDDIR%/.. 163 | echo. 164 | echo.Build finished; the PDF files are in %BUILDDIR%/latex. 165 | goto end 166 | ) 167 | 168 | if "%1" == "text" ( 169 | %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text 170 | if errorlevel 1 exit /b 1 171 | echo. 172 | echo.Build finished. The text files are in %BUILDDIR%/text. 173 | goto end 174 | ) 175 | 176 | if "%1" == "man" ( 177 | %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man 178 | if errorlevel 1 exit /b 1 179 | echo. 180 | echo.Build finished. The manual pages are in %BUILDDIR%/man. 181 | goto end 182 | ) 183 | 184 | if "%1" == "texinfo" ( 185 | %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo 186 | if errorlevel 1 exit /b 1 187 | echo. 188 | echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. 189 | goto end 190 | ) 191 | 192 | if "%1" == "gettext" ( 193 | %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale 194 | if errorlevel 1 exit /b 1 195 | echo. 196 | echo.Build finished. The message catalogs are in %BUILDDIR%/locale. 197 | goto end 198 | ) 199 | 200 | if "%1" == "changes" ( 201 | %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes 202 | if errorlevel 1 exit /b 1 203 | echo. 204 | echo.The overview file is in %BUILDDIR%/changes. 205 | goto end 206 | ) 207 | 208 | if "%1" == "linkcheck" ( 209 | %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck 210 | if errorlevel 1 exit /b 1 211 | echo. 212 | echo.Link check complete; look for any errors in the above output ^ 213 | or in %BUILDDIR%/linkcheck/output.txt. 214 | goto end 215 | ) 216 | 217 | if "%1" == "doctest" ( 218 | %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest 219 | if errorlevel 1 exit /b 1 220 | echo. 221 | echo.Testing of doctests in the sources finished, look at the ^ 222 | results in %BUILDDIR%/doctest/output.txt. 223 | goto end 224 | ) 225 | 226 | if "%1" == "xml" ( 227 | %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml 228 | if errorlevel 1 exit /b 1 229 | echo. 230 | echo.Build finished. The XML files are in %BUILDDIR%/xml. 231 | goto end 232 | ) 233 | 234 | if "%1" == "pseudoxml" ( 235 | %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml 236 | if errorlevel 1 exit /b 1 237 | echo. 238 | echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. 239 | goto end 240 | ) 241 | 242 | :end 243 | -------------------------------------------------------------------------------- /source/about.rst: -------------------------------------------------------------------------------- 1 | *************** 2 | About This Book 3 | *************** 4 | 5 | 6 | Copying 7 | ======= 8 | 9 | All source code used in this book is Free Software, released under the 10 | `terms of the GPL v3`_. 11 | 12 | The remainder of the book is released under a 13 | `Creative Commons Attribution-ShareAlike 3.0 Unported License`_. 14 | 15 | .. raw:: html 16 | 17 | Creative Commons License 18 | 19 | 20 | `Sing along with Richard Stallman`_, founder of the Free Software movement! 21 | 22 | 23 | Resources 24 | ========= 25 | 26 | The Sphinx_ `source code`_ for this book is available on on Github. 27 | 28 | The latest version of this book is published at `Read the Docs`_. It is also 29 | available in PDF_ and ePub_ formats. 30 | 31 | 32 | Classroom Instruction 33 | ===================== 34 | 35 | Classroom instruction in Go, Python, SQL, REST API development, cloud 36 | deployment, and continuous integration is available from the author in Silicon 37 | Valley, or on demand anywhere in the world, for groups of five to twelve 38 | students. `Contact the author`_ for more information. 39 | 40 | 41 | Related Courses 42 | =============== 43 | 44 | .. todo:: 45 | 46 | Add related courses. 47 | 48 | 49 | Author 50 | ====== 51 | 52 | `Jason McVetta`_ is an independent consultant, teacher, and Free Software 53 | activist based in beautiful-but-too-cold San Francisco. He studied government 54 | and philosophy in college, but was unwilling to sell his soul to the 55 | Demopublicratican Party, so he went to work in software. After 12 years as a 56 | professional Pythonist he met his new love, Go. He is able to fly without 57 | mechanical assistance. 58 | 59 | 60 | Payment 61 | ======= 62 | 63 | This is a Free book, but you are more than welcome to pay me for it! You are 64 | under no obligation, legal or moral, to do so. But I can always use a couple 65 | bucks for coffee. =) 66 | 67 | .. raw:: html 68 | 69 |
70 | 71 | 72 | 73 | 74 | 75 | .. _`Contact the author`: mailto:jason.mcvetta@gmail.com 76 | .. _`terms of the GPL v3`: http://www.gnu.org/copyleft/gpl.html 77 | .. _`Sing along with Richard Stallman`: https://upload.wikimedia.org/wikipedia/commons/9/9c/Stallman_free_software_song.ogv 78 | .. _`Creative Commons Attribution-ShareAlike 3.0 Unported License`: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US 79 | .. _PDF: https://media.readthedocs.org/pdf/golang-for-python-programmers/latest/golang-for-python-programmers.pdf 80 | .. _ePub: https://media.readthedocs.org/epub/golang-for-python-programmers/latest/golang-for-python-programmers.epub 81 | .. _Sphinx: http://sphinx-doc.org 82 | .. _`source code`: http://github.com/jmcvetta/golang-for-python-programmers 83 | .. _`Read the Docs`: http://golang-for-python-programmers.readthedocs.org/ 84 | .. _`Jason McVetta`: mailto:jason.mcvetta@gmail.com 85 | .. _`continuous integration`: https://en.wikipedia.org/wiki/Continuous_integration 86 | .. _cloud: http://en.wikipedia.org/wiki/Cloud_computing 87 | .. _`Jason McVetta`: mailto:jason.mcvetta@gmail.com 88 | 89 | 90 | .. rubric:: Citations 91 | 92 | .. [#cit1] https://en.wikipedia.org/wiki/Go_(programming_language) 93 | -------------------------------------------------------------------------------- /source/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Go for Python Programmers documentation build configuration file, created by 4 | # sphinx-quickstart on Mon Jul 8 13:40:33 2013. 5 | # 6 | # This file is execfile()d with the current directory set to its containing dir. 7 | # 8 | # Note that not all possible configuration values are present in this 9 | # autogenerated file. 10 | # 11 | # All configuration values have a default; values that are commented out 12 | # serve to show the default. 13 | 14 | import sys, os 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | #sys.path.insert(0, os.path.abspath('.')) 20 | 21 | # -- General configuration ----------------------------------------------------- 22 | 23 | # If your documentation needs a minimal Sphinx version, state it here. 24 | #needs_sphinx = '1.0' 25 | 26 | # Add any Sphinx extension module names here, as strings. They can be extensions 27 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 28 | extensions = ['sphinx.ext.todo', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode'] 29 | 30 | # Add any paths that contain templates here, relative to this directory. 31 | templates_path = ['_templates'] 32 | 33 | # The suffix of source filenames. 34 | source_suffix = '.rst' 35 | 36 | # The encoding of source files. 37 | #source_encoding = 'utf-8-sig' 38 | 39 | # The master toctree document. 40 | master_doc = 'index' 41 | 42 | # General information about the project. 43 | project = u'Go for Python Programmers' 44 | copyright = u'2013, Jason McVetta' 45 | 46 | # The version info for the project you're documenting, acts as replacement for 47 | # |version| and |release|, also used in various other places throughout the 48 | # built documents. 49 | # 50 | # The short X.Y version. 51 | version = '0.1' 52 | # The full version, including alpha/beta/rc tags. 53 | release = '0.1a' 54 | 55 | # The language for content autogenerated by Sphinx. Refer to documentation 56 | # for a list of supported languages. 57 | #language = None 58 | 59 | # There are two options for replacing |today|: either, you set today to some 60 | # non-false value, then it is used: 61 | #today = '' 62 | # Else, today_fmt is used as the format for a strftime call. 63 | #today_fmt = '%B %d, %Y' 64 | 65 | # List of patterns, relative to source directory, that match files and 66 | # directories to ignore when looking for source files. 67 | exclude_patterns = [] 68 | 69 | # The reST default role (used for this markup: `text`) to use for all documents. 70 | #default_role = None 71 | 72 | # If true, '()' will be appended to :func: etc. cross-reference text. 73 | #add_function_parentheses = True 74 | 75 | # If true, the current module name will be prepended to all description 76 | # unit titles (such as .. function::). 77 | #add_module_names = True 78 | 79 | # If true, sectionauthor and moduleauthor directives will be shown in the 80 | # output. They are ignored by default. 81 | #show_authors = False 82 | 83 | # The name of the Pygments (syntax highlighting) style to use. 84 | pygments_style = 'sphinx' 85 | 86 | # A list of ignored prefixes for module index sorting. 87 | #modindex_common_prefix = [] 88 | 89 | # If true, keep warnings as "system message" paragraphs in the built documents. 90 | #keep_warnings = False 91 | 92 | 93 | # -- Options for HTML output --------------------------------------------------- 94 | 95 | # The theme to use for HTML and HTML Help pages. See the documentation for 96 | # a list of builtin themes. 97 | html_theme = 'default' 98 | 99 | # Theme options are theme-specific and customize the look and feel of a theme 100 | # further. For a list of options available for each theme, see the 101 | # documentation. 102 | #html_theme_options = {} 103 | 104 | # Add any paths that contain custom themes here, relative to this directory. 105 | #html_theme_path = [] 106 | 107 | # The name for this set of Sphinx documents. If None, it defaults to 108 | # " v documentation". 109 | #html_title = None 110 | 111 | # A shorter title for the navigation bar. Default is the same as html_title. 112 | #html_short_title = None 113 | 114 | # The name of an image file (relative to this directory) to place at the top 115 | # of the sidebar. 116 | #html_logo = None 117 | 118 | # The name of an image file (within the static path) to use as favicon of the 119 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 120 | # pixels large. 121 | #html_favicon = None 122 | 123 | # Add any paths that contain custom static files (such as style sheets) here, 124 | # relative to this directory. They are copied after the builtin static files, 125 | # so a file named "default.css" will overwrite the builtin "default.css". 126 | html_static_path = ['_static'] 127 | 128 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 129 | # using the given strftime format. 130 | #html_last_updated_fmt = '%b %d, %Y' 131 | 132 | # If true, SmartyPants will be used to convert quotes and dashes to 133 | # typographically correct entities. 134 | #html_use_smartypants = True 135 | 136 | # Custom sidebar templates, maps document names to template names. 137 | #html_sidebars = {} 138 | 139 | # Additional templates that should be rendered to pages, maps page names to 140 | # template names. 141 | #html_additional_pages = {} 142 | 143 | # If false, no module index is generated. 144 | #html_domain_indices = True 145 | 146 | # If false, no index is generated. 147 | #html_use_index = True 148 | 149 | # If true, the index is split into individual pages for each letter. 150 | #html_split_index = False 151 | 152 | # If true, links to the reST sources are added to the pages. 153 | #html_show_sourcelink = True 154 | 155 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 156 | #html_show_sphinx = True 157 | 158 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 159 | #html_show_copyright = True 160 | 161 | # If true, an OpenSearch description file will be output, and all pages will 162 | # contain a tag referring to it. The value of this option must be the 163 | # base URL from which the finished HTML is served. 164 | #html_use_opensearch = '' 165 | 166 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 167 | #html_file_suffix = None 168 | 169 | # Output file base name for HTML help builder. 170 | htmlhelp_basename = 'GoforPythonProgrammersdoc' 171 | 172 | 173 | # -- Options for LaTeX output -------------------------------------------------- 174 | 175 | latex_elements = { 176 | # The paper size ('letterpaper' or 'a4paper'). 177 | #'papersize': 'letterpaper', 178 | 179 | # The font size ('10pt', '11pt' or '12pt'). 180 | #'pointsize': '10pt', 181 | 182 | # Additional stuff for the LaTeX preamble. 183 | #'preamble': '', 184 | } 185 | 186 | # Grouping the document tree into LaTeX files. List of tuples 187 | # (source start file, target name, title, author, documentclass [howto/manual]). 188 | latex_documents = [ 189 | ('index', 'GoforPythonProgrammers.tex', u'Go for Python Programmers Documentation', 190 | u'Jason McVetta', 'manual'), 191 | ] 192 | 193 | # The name of an image file (relative to this directory) to place at the top of 194 | # the title page. 195 | #latex_logo = None 196 | 197 | # For "manual" documents, if this is true, then toplevel headings are parts, 198 | # not chapters. 199 | #latex_use_parts = False 200 | 201 | # If true, show page references after internal links. 202 | #latex_show_pagerefs = False 203 | 204 | # If true, show URL addresses after external links. 205 | #latex_show_urls = False 206 | 207 | # Documents to append as an appendix to all manuals. 208 | #latex_appendices = [] 209 | 210 | # If false, no module index is generated. 211 | #latex_domain_indices = True 212 | 213 | 214 | # -- Options for manual page output -------------------------------------------- 215 | 216 | # One entry per manual page. List of tuples 217 | # (source start file, name, description, authors, manual section). 218 | man_pages = [ 219 | ('index', 'goforpythonprogrammers', u'Go for Python Programmers Documentation', 220 | [u'Jason McVetta'], 1) 221 | ] 222 | 223 | # If true, show URL addresses after external links. 224 | #man_show_urls = False 225 | 226 | 227 | # -- Options for Texinfo output ------------------------------------------------ 228 | 229 | # Grouping the document tree into Texinfo files. List of tuples 230 | # (source start file, target name, title, author, 231 | # dir menu entry, description, category) 232 | texinfo_documents = [ 233 | ('index', 'GoforPythonProgrammers', u'Go for Python Programmers Documentation', 234 | u'Jason McVetta', 'GoforPythonProgrammers', 'One line description of project.', 235 | 'Miscellaneous'), 236 | ] 237 | 238 | # Documents to append as an appendix to all manuals. 239 | #texinfo_appendices = [] 240 | 241 | # If false, no module index is generated. 242 | #texinfo_domain_indices = True 243 | 244 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 245 | #texinfo_show_urls = 'footnote' 246 | 247 | # If true, do not generate a @detailmenu in the "Top" node's menu. 248 | #texinfo_no_detailmenu = False 249 | 250 | 251 | # -- Options for Epub output --------------------------------------------------- 252 | 253 | # Bibliographic Dublin Core info. 254 | epub_title = u'Go for Python Programmers' 255 | epub_author = u'Jason McVetta' 256 | epub_publisher = u'Jason McVetta' 257 | epub_copyright = u'2013, Jason McVetta' 258 | 259 | # The language of the text. It defaults to the language option 260 | # or en if the language is not set. 261 | #epub_language = '' 262 | 263 | # The scheme of the identifier. Typical schemes are ISBN or URL. 264 | #epub_scheme = '' 265 | 266 | # The unique identifier of the text. This can be a ISBN number 267 | # or the project homepage. 268 | #epub_identifier = '' 269 | 270 | # A unique identification for the text. 271 | #epub_uid = '' 272 | 273 | # A tuple containing the cover image and cover page html template filenames. 274 | #epub_cover = () 275 | 276 | # A sequence of (type, uri, title) tuples for the guide element of content.opf. 277 | #epub_guide = () 278 | 279 | # HTML files that should be inserted before the pages created by sphinx. 280 | # The format is a list of tuples containing the path and title. 281 | #epub_pre_files = [] 282 | 283 | # HTML files shat should be inserted after the pages created by sphinx. 284 | # The format is a list of tuples containing the path and title. 285 | #epub_post_files = [] 286 | 287 | # A list of files that should not be packed into the epub file. 288 | #epub_exclude_files = [] 289 | 290 | # The depth of the table of contents in toc.ncx. 291 | #epub_tocdepth = 3 292 | 293 | # Allow duplicate toc entries. 294 | #epub_tocdup = True 295 | 296 | # Fix unsupported image types using the PIL. 297 | #epub_fix_images = False 298 | 299 | # Scale large images. 300 | #epub_max_image_width = 0 301 | 302 | # If 'no', URL addresses will not be shown. 303 | #epub_show_urls = 'inline' 304 | 305 | # If false, no index is generated. 306 | #epub_use_index = True 307 | 308 | 309 | # ToDo 310 | todo_include_todos = True -------------------------------------------------------------------------------- /source/doc.rst: -------------------------------------------------------------------------------- 1 | ************* 2 | Documentation 3 | ************* 4 | 5 | Good documentation is an essential part of any Go program. You will frequently 6 | need to read and understand the documentation for 3rd Party Open Source 7 | libraries. As you become a skilled Gopher you will probably also want to 8 | publish your own Open Source packages. A well-documented package attracts more 9 | users, and reflects well on its author. 10 | 11 | 12 | Self-Documenting Code 13 | ===================== 14 | 15 | Go code is `self-documenting`_, meaning the source code explains itself without 16 | needing external documentation. If you include doc comments in your code as 17 | described below, tools like ``godoc`` will automatically generate useful 18 | documentation for your packages. [#cit1]_ 19 | 20 | Package Comments 21 | ---------------- 22 | 23 | Every package should have a *package comment*, a block comment preceding the 24 | package clause. For multi-file packages, the package comment only needs to be 25 | present in one file, and any one will do. The package comment should introduce 26 | the package and provide information relevant to the package as a whole. It will 27 | appear first on the godoc page and should set up the detailed documentation that 28 | follows. 29 | 30 | .. code-block:: go 31 | 32 | /* 33 | Package regexp implements a simple library for regular expressions. 34 | 35 | The syntax of the regular expressions accepted is: 36 | 37 | regexp: 38 | concatenation { '|' concatenation } 39 | concatenation: 40 | { closure } 41 | closure: 42 | term [ '*' | '+' | '?' ] 43 | term: 44 | '^' 45 | '$' 46 | '.' 47 | character 48 | '[' [ '^' ] character-ranges ']' 49 | '(' regexp ')' 50 | */ 51 | package regexp 52 | 53 | If the package is simple, the package comment can be brief. 54 | 55 | .. code-block:: go 56 | 57 | // Package path implements utility routines for 58 | // manipulating slash-separated filename paths. 59 | package path 60 | 61 | Comments do not need extra formatting such as banners of stars. The generated 62 | output may not even be presented in a fixed-width font, so don't depend on 63 | spacing for alignment—godoc, like gofmt, takes care of that. The comments are 64 | uninterpreted plain text, so HTML and other annotations such as _this_ will 65 | reproduce verbatim and should not be used. One adjustment godoc does do is to 66 | display indented text in a fixed-width font, suitable for program snippets. The 67 | package comment for the fmt package uses this to good effect. 68 | 69 | Depending on the context, godoc might not even reformat comments, so make sure 70 | they look good straight up: use correct spelling, punctuation, and sentence 71 | structure, fold long lines, and so on. 72 | 73 | Doc Comments 74 | ------------ 75 | 76 | Inside a package, any comment immediately preceding a top-level declaration 77 | serves as a *doc comment* for that declaration. Every exported (capitalized) 78 | name in a program should have a doc comment. 79 | 80 | Doc comments work best as complete sentences, which allow a wide variety of 81 | automated presentations. The first sentence should be a one-sentence summary 82 | that starts with the name being declared. 83 | 84 | .. code-block:: go 85 | 86 | // Compile parses a regular expression and returns, if successful, a Regexp 87 | // object that can be used to match against text. 88 | func Compile(str string) (regexp *Regexp, err error) { 89 | 90 | If the name always begins the comment, the output of godoc can usefully be run 91 | through grep. Imagine you couldn't remember the name "Compile" but were looking 92 | for the parsing function for regular expressions, so you ran the command, 93 | 94 | .. code-block:: console 95 | 96 | $ godoc regexp | grep parse 97 | 98 | If all the doc comments in the package began, "This function...", grep wouldn't 99 | help you remember the name. But because the package starts each doc comment with 100 | the name, you'd see something like this, which recalls the word you're looking 101 | for. 102 | 103 | .. code-block:: console 104 | 105 | $ godoc regexp | grep parse 106 | Compile parses a regular expression and returns, if successful, a Regexp 107 | parsed. It simplifies safe initialization of global variables holding 108 | cannot be parsed. It simplifies safe initialization of global variables 109 | $ 110 | 111 | Go's declaration syntax allows grouping of declarations. A single doc comment 112 | can introduce a group of related constants or variables. Since the whole 113 | declaration is presented, such a comment can often be perfunctory. 114 | 115 | .. code-block:: go 116 | 117 | // Error codes returned by failures to parse an expression. 118 | var ( 119 | ErrInternal = errors.New("regexp: internal error") 120 | ErrUnmatchedLpar = errors.New("regexp: unmatched '('") 121 | ErrUnmatchedRpar = errors.New("regexp: unmatched ')'") 122 | ... 123 | ) 124 | 125 | 126 | Uncommented Code Is Broken 127 | -------------------------- 128 | 129 | Seriously, if your code doesn't have good doc comments, it is by definition lousy code. 130 | 131 | .. todo:: 132 | 133 | Write a short diatribe on the importance of code commentary. 134 | 135 | 136 | ``godoc`` tool 137 | ============== 138 | 139 | Godoc extracts and generates documentation for Go programs. [#cit2]_ 140 | 141 | It has two modes. 142 | 143 | Without the ``-http`` flag, it runs in command-line mode and prints plain text 144 | documentation to standard output and exits. If both a library package and a 145 | command with the same name exists, using the prefix cmd/ will force 146 | documentation on the command rather than the library package. If the ``-src`` 147 | flag is specified, godoc prints the exported interface of a package in Go source 148 | form, or the implementation of a specific exported language entity:: 149 | 150 | godoc fmt # documentation for package fmt 151 | godoc fmt Printf # documentation for fmt.Printf 152 | godoc cmd/go # force documentation for the go command 153 | godoc -src fmt # fmt package interface in Go source form 154 | godoc -src fmt Printf # implementation of fmt.Printf 155 | 156 | With the ``-http`` flag, it runs as a web server and presents the documentation 157 | as a web page. 158 | 159 | :: 160 | 161 | godoc -http=:6060 162 | 163 | 164 | 165 | GoDoc.org 166 | ========= 167 | 168 | GoDoc_ is an open source web application that displays documentation for Go 169 | packages on Bitbucket, Github, Launchpad and Google Project Hosting. It is 170 | similar to the ``godoc`` command, but can display documentation for any open 171 | source Go module specified by its import URL. 172 | 173 | 174 | Using GoDoc.org 175 | --------------- 176 | 177 | To view a package's documentation on GoDoc.org you enter its import path. Let's 178 | check out the docs for ``mgo``, the popular MongoDB database driver. Its import 179 | path is ``labix.org/v2/mgo``. 180 | 181 | .. image:: images/godoc-mgo/search.png 182 | :width: 50% 183 | 184 | We could also haved typed in just "mgo" and GoDoc would show us packages with 185 | that string in their name. However it is does not attempt to rank results by 186 | relevance or popularity, so the actual ``mgo`` driver would not be one of the 187 | first few results. 188 | 189 | Click "Go!" and GoDoc will display the documentation for our package. The 190 | documentation starts with the package's name, import path, and package comment. 191 | 192 | .. image:: images/godoc-mgo/package.png 193 | :width: 50% 194 | 195 | Up next is an alphabetical index of all the exported entities in the package - 196 | constants, variables, types, and functions. Methods are displayed beneath the 197 | type to which they are bound. 198 | 199 | .. image:: images/godoc-mgo/index.png 200 | :width: 50% 201 | 202 | Click on the index entry for ``Collection`` to be taken to its detailed 203 | documentation. The exported fields and methods of structs are displayed, as 204 | well as the type signature of functions and methods. The entity's doc comment 205 | is displayed, if it has one. 206 | 207 | .. image:: images/godoc-mgo/collection.png 208 | :width: 50% 209 | 210 | Sometimes the documentation is not enough, and we want to look at the source 211 | code. Click on the function name ``Count`` to see its source. 212 | 213 | .. image:: images/godoc-mgo/src-count.png 214 | :width: 50% 215 | 216 | 217 | Open Source 218 | ----------- 219 | 220 | GoDoc.org is open source! If you want to see how it works, check out 221 | https://github.com/garyburd/gddo! 222 | 223 | Go Walker 224 | --------- 225 | 226 | Also check out `Go Walker`_, a new enhanced version of GoDoc that displays code 227 | snippets alongside the documentation. 228 | 229 | 230 | 231 | .. _GoDoc: http://godoc.org 232 | .. _`self-documenting`: http://en.wikipedia.org/wiki/Self-documenting 233 | .. _`Go Walker`: http://gowalker.org 234 | 235 | 236 | .. rubric:: Citations 237 | 238 | .. [#cit1] The following sections mostly copied from http://golang.org/doc/effective_go.html#commentary 239 | .. [#cit2] The following section copied from the package comment of ``godoc`` -------------------------------------------------------------------------------- /source/examples/go/hello_deps/src/github.com/jmcvetta/hello/greeter/greeter.go: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013 Jason McVetta. This is Free Software, released under the 2 | // terms of the GPL v3. See http://www.gnu.org/copyleft/gpl.html for details. 3 | // Resist intellectual serfdom - the ownership of ideas is akin to slavery. 4 | 5 | package greeter 6 | 7 | import ( 8 | "github.com/darkhelmet/env" 9 | "time" 10 | ) 11 | 12 | // Greeting returns a pleasant, semi-useful greeting. 13 | func Greeting() string { 14 | msg := "Hello world, the time is " 15 | msg += time.Now().String() 16 | msg += " and your PATH is " 17 | msg += env.String("PATH") 18 | return msg 19 | } 20 | -------------------------------------------------------------------------------- /source/examples/go/hello_deps/src/github.com/jmcvetta/hello/hello.go: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013 Jason McVetta. This is Free Software, released under the 2 | // terms of the GPL v3. See http://www.gnu.org/copyleft/gpl.html for details. 3 | // Resist intellectual serfdom - the ownership of ideas is akin to slavery. 4 | 5 | package main 6 | 7 | import ( 8 | "fmt" 9 | "github.com/jmcvetta/hello/greeter" 10 | ) 11 | 12 | func main() { 13 | fmt.Println(greeter.Greeting()) 14 | } 15 | -------------------------------------------------------------------------------- /source/examples/go/src/hello/hello.go: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2013 Jason McVetta. This is Free Software, released under the 2 | // terms of the GPL v3. See http://www.gnu.org/copyleft/gpl.html for details. 3 | // Resist intellectual serfdom - the ownership of ideas is akin to slavery. 4 | 5 | // A "Hello World" program that prints a greeting with the current time. 6 | package main 7 | 8 | import ( 9 | "fmt" 10 | "time" 11 | ) 12 | 13 | // greeting returns a pleasant, semi-useful greeting. 14 | func greeting() string { 15 | return "Hello world, the time is: " + time.Now().String() 16 | } 17 | 18 | // needlesslyComplexGreeting uses needlessly complex operations to return a 19 | // pleasant, semi-useful greeting. 20 | func needlesslyComplexGreeting() string { 21 | var now string 22 | now = time.Now().String() 23 | msg := "Hello world, the time is: " 24 | msg += now 25 | return msg 26 | } 27 | 28 | func main() { 29 | fmt.Println(greeting()) 30 | } 31 | -------------------------------------------------------------------------------- /source/examples/python/hello/hello.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # 3 | # Copyright (c) 2013 Jason McVetta. This is Free Software, released under the 4 | # terms of the GPL v3. See http://www.gnu.org/copyleft/gpl.html for details. 5 | # Resist intellectual serfdom - the ownership of ideas is akin to slavery. 6 | 7 | import time 8 | 9 | 10 | def greeting(): 11 | '''Returns a pleasant, semi-useful greeting.''' 12 | return "Hello world, the time is: " + time.ctime() 13 | 14 | 15 | def main(): 16 | print greeting() 17 | 18 | 19 | if __name__ == '__main__': 20 | main() 21 | 22 | -------------------------------------------------------------------------------- /source/godoc.time.now.txt: -------------------------------------------------------------------------------- 1 | $ godoc time Now String 2 | PACKAGE DOCUMENTATION 3 | 4 | package time 5 | import "time" 6 | 7 | [ ... ] 8 | 9 | type Time struct { 10 | // contains filtered or unexported fields 11 | } 12 | A Time represents an instant in time with nanosecond precision. 13 | 14 | Programs using times should typically store and pass them as values, not 15 | pointers. That is, time variables and struct fields should be of type 16 | time.Time, not *time.Time. A Time value can be used by multiple 17 | goroutines simultaneously. 18 | 19 | Time instants can be compared using the Before, After, and Equal 20 | methods. The Sub method subtracts two instants, producing a Duration. 21 | The Add method adds a Time and a Duration, producing a Time. 22 | 23 | The zero value of type Time is January 1, year 1, 00:00:00.000000000 24 | UTC. As this time is unlikely to come up in practice, the IsZero method 25 | gives a simple way of detecting a time that has not been initialized 26 | explicitly. 27 | 28 | Each Time has associated with it a Location, consulted when computing 29 | the presentation form of the time, such as in the Format, Hour, and Year 30 | methods. The methods Local, UTC, and In return a Time with a specific 31 | location. Changing the location in this way changes only the 32 | presentation; it does not change the instant in time being denoted and 33 | therefore does not affect the computations described in earlier 34 | paragraphs. 35 | 36 | func Now() Time 37 | Now returns the current local time. 38 | 39 | 40 | func (t Time) String() string 41 | String returns the time formatted using the format string 42 | 43 | "2006-01-02 15:04:05.999999999 -0700 MST" 44 | 45 | 46 | [ ... ] -------------------------------------------------------------------------------- /source/hello.rst: -------------------------------------------------------------------------------- 1 | ************* 2 | Hello, World! 3 | ************* 4 | 5 | Let's start out with a Hello World example. Our program will greet the world 6 | with a hello and the current time. 7 | 8 | In Python it looks something like this: 9 | 10 | .. literalinclude:: examples/python/hello/hello.py 11 | :linenos: 12 | :lines: 1,6- 13 | 14 | 15 | It's not that different in Go: 16 | 17 | 18 | .. literalinclude:: examples/go/src/hello/hello.go 19 | :linenos: 20 | :language: go 21 | :lines: 5-17,28- 22 | 23 | 24 | Curly Braces 25 | ============ 26 | 27 | The first thing one may notice is that whereas Python uses whitespace to denote 28 | scope, Go uses curly braces. The Go authors did, however, take a lesson from 29 | Python's culture of readable code. Although it is certainly possible to write 30 | syntactically valid Go code without any indentation at all, nevertheless almost 31 | all Go code one sees is formatted consistently and readably. That's because, 32 | Go includes a code formatter along with the compiler. The formatter, ``gofmt``, 33 | is considered canonically correct by the Go community - if you don't like how 34 | ``gofmt`` formats your code, *you are wrong*. It is customary that ``gofmt`` 35 | always be run before checking in code. 36 | 37 | .. code-block:: console 38 | 39 | $ gofmt -w hello.go # -w option updates the file(s) in place 40 | 41 | 42 | Package 43 | ======= 44 | 45 | In any ``.go`` file, the first non-comment line is a ``package`` declaration. 46 | The package declaration is mandatory - *every* ``.go`` file must begin with one. 47 | Every ``.go`` file in the same folder must have the same package name. 48 | 49 | The ``package`` declaration is preceded by a comment, called the *package 50 | comment*. Automatic documentation tools like ``godoc`` extract the package 51 | comment as the description of your program. 52 | 53 | .. literalinclude:: examples/go/src/hello/hello.go 54 | :language: go 55 | :lines: 5-6 56 | 57 | 58 | Import 59 | ====== 60 | 61 | Next comes the ``import`` declaration. Although it is optional, most ``.go`` 62 | files will have one. Each package to be imported is listed on a separate line, 63 | inside quotation marks. The packages in our example, ``fmt`` and ``time``, come 64 | from the standard library. By convention, 3rd-party packages are named after 65 | their repository URL. For example, my Neo4j library hosted on Github would be 66 | imported as ``"github.com/jmcvetta/neo4j"``. 67 | 68 | .. literalinclude:: examples/go/src/hello/hello.go 69 | :language: go 70 | :lines: 7-11 71 | 72 | Functions 73 | ========= 74 | 75 | Our program has two functions, ``greeting()`` and ``main()``. 76 | 77 | The function ``greeting()`` takes no arguments, and returns a string. Unlike 78 | Java and C, in Go the type declaration *follows* the function name. Like all 79 | good function declarations, this one includes a doc comment describing what it 80 | does. 81 | 82 | .. literalinclude:: examples/go/src/hello/hello.go 83 | :language: go 84 | :lines: 13-14 85 | 86 | Return 87 | ====== 88 | 89 | Every function that declares a return type, must end with a ``return`` 90 | statement. In this case we add a literal string to the output of 91 | ``time.Now().String()`` 92 | 93 | Let's look at the documentatation for ``time``. We can see that ``time.Now()`` 94 | returns an instance of type ``Time``. That instance, in turn, exports a 95 | ``String()`` method that unsurprisingly returns a ``string``. Using the 96 | addition operator with two strings results in the strings being concatenated. 97 | If we had tried to add our greeting string to just ``time.Now()`` the code would 98 | not compile, due to type mismatch. 99 | 100 | .. literalinclude:: godoc.time.now.txt 101 | :language: console 102 | :emphasize-lines: 36-43 103 | 104 | Variables 105 | ========= 106 | 107 | Python is dynamically typed. That means there is no difference between variable 108 | assignment and declaration. For example, saying ``x = 3`` is equally valid if 109 | ``x`` was previously undeclared, or if it was already declared as an integer, or 110 | even if it was already declared as e.g. a string. 111 | 112 | Go, on the other hand, is statically typed. A variable must be declared as a 113 | specific type before a value can be assigned to it. Once declared, a variable 114 | may only be assigned values of its declared type. Go also provides an operator, 115 | ``:=``, that combined declaration and assignment in the same statement. 116 | 117 | Let's look at a needlessly complex version of our greeting function to see how 118 | variable declaration and assignment work. 119 | 120 | .. literalinclude:: examples/go/src/hello/hello.go 121 | :language: go 122 | :lines: 18-26 123 | :linenos: 124 | 125 | On line 4 we used the ``var`` keyword to declare the variable ``now`` as a 126 | string. It is initially set to the `zero value`_ for ``string`` type, which is 127 | "" the empty string. Line 5 assigns the (string) return value of 128 | ``time.Now().String()`` to ``now``. 129 | 130 | On line 6 we use the `short variable declaration`_ syntax to declare ``msg`` as 131 | a ``string``, and immediately assign it the value of a literal string. The 132 | resulting variable is exactly the same as if we had declared it as ``var msg 133 | string`` on a seperate line. 134 | 135 | Line 7 appends the value of ``now`` to the value of ``msg``, working in this 136 | case exactly like Python's ``+=`` operator. However unlike Python, *only* 137 | strings can be added to other strings, no automatic type coercion is ever 138 | attempted. 139 | 140 | ``main()`` 141 | ========== 142 | 143 | Our Hello World program declares its package as ``main``, and contains a special 144 | function ``main()``. That tells Go to compile this code as an executable 145 | program, with the entry point at ``main()``. The function ``main()`` has no 146 | arguments and no return value. Command line arguments - called "argv" in many 147 | languages - are available from the standard library, either raw from 148 | ``os.Args``, or with higher level abstraction from the package ``flag``. 149 | 150 | 151 | Compiling 152 | ========= 153 | 154 | Python is an interpretted language - our program can be run immediately with the 155 | ``python`` command: 156 | 157 | .. code-block:: console 158 | 159 | $ python hello.py 160 | Hello world, the time is: Sat Jul 13 12:49:14 2013 161 | 162 | Go on the other hand is a compiled language - our source code must first be 163 | compiled into an executable binary before we can run it. We will use the ``go`` 164 | command line tool to access the compiler. 165 | 166 | ``go run`` 167 | ---------- 168 | 169 | As a convenience, the ``go`` tool provides a ``run`` command that first compiles 170 | the specified file(s), then executes the resulting binary. Given Go's 171 | lightning-quick compile times, using ``go run`` can feel similar to working with 172 | an interpretted language like Python or Ruby. 173 | 174 | .. code-block:: console 175 | 176 | $ go run hello.go 177 | Hello world, the time is: 2013-07-13 13:01:23.837155926 -0700 PDT 178 | 179 | Only programs that declare ``package main`` -- in other words, those which can 180 | be compiled into an executable application -- can be run with ``go run``. Note 181 | that all files to be compiled must be specified on the command line, even tho 182 | they are all declared as part of the same package. 183 | 184 | Running code with ``go run`` does *not* leave an executable binary file laying 185 | around - it is deleted immediately after it is run. 186 | 187 | ``go build`` 188 | ------------ 189 | 190 | We can use the ``go build`` command to compile our code into an executable 191 | binary. The binary is statically linked, and can be redistributed (on the same 192 | platform) just by copying it, with no dependencies. The binary file is created 193 | in the same folder that contains the source code. 194 | 195 | .. code-block:: console 196 | 197 | $ ls 198 | hello.go 199 | 200 | $ go build -v . 201 | hello 202 | 203 | $ ls 204 | hello* hello.go 205 | 206 | $ ./hello 207 | Hello world, the time is: 2013-07-13 13:07:57.150564433 -0700 PDT 208 | 209 | 210 | ``go install`` 211 | -------------- 212 | 213 | The ``go install`` command works like ``go build``, except instead of putting 214 | the binary file in the source code folder, it installs it to 215 | ``$GOPATH/bin``. If ``$GOPATH/bin`` is on your ``$PATH``, your program will be 216 | available as a command after running ``go install``. 217 | 218 | .. code-block:: console 219 | 220 | $ ls 221 | hello.go 222 | 223 | $ go install -v . 224 | hello 225 | 226 | $ ls 227 | hello.go 228 | 229 | $ ls $GOPATH/bin 230 | hello* 231 | 232 | 233 | 234 | .. _`zero value`: http://golang.org/ref/spec#The_zero_value 235 | .. _`short variable declaration`: http://golang.org/ref/spec#Short_variable_declarations 236 | -------------------------------------------------------------------------------- /source/images/godoc-mgo/collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jmcvetta/golang-for-python-programmers/96389478535301014f7e921857873aeac9001726/source/images/godoc-mgo/collection.png -------------------------------------------------------------------------------- /source/images/godoc-mgo/index.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jmcvetta/golang-for-python-programmers/96389478535301014f7e921857873aeac9001726/source/images/godoc-mgo/index.png -------------------------------------------------------------------------------- /source/images/godoc-mgo/package.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jmcvetta/golang-for-python-programmers/96389478535301014f7e921857873aeac9001726/source/images/godoc-mgo/package.png -------------------------------------------------------------------------------- /source/images/godoc-mgo/search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jmcvetta/golang-for-python-programmers/96389478535301014f7e921857873aeac9001726/source/images/godoc-mgo/search.png -------------------------------------------------------------------------------- /source/images/godoc-mgo/src-count.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jmcvetta/golang-for-python-programmers/96389478535301014f7e921857873aeac9001726/source/images/godoc-mgo/src-count.png -------------------------------------------------------------------------------- /source/index.rst: -------------------------------------------------------------------------------- 1 | ************************* 2 | Go for Python Programmers 3 | ************************* 4 | 5 | This book is intended to provide a solid introduction to the Go_ language 6 | for experienced Python programmers. 7 | 8 | **Contents** 9 | 10 | .. toctree:: 11 | :maxdepth: 2 12 | 13 | about 14 | intro 15 | setup 16 | hello 17 | doc 18 | toolchain 19 | layout 20 | 21 | * :ref:`Search this Book ` 22 | 23 | 24 | .. _Go: http://golang.org -------------------------------------------------------------------------------- /source/intro.rst: -------------------------------------------------------------------------------- 1 | ************ 2 | Introduction 3 | ************ 4 | 5 | .. pull-quote:: 6 | 7 | Go is like C and Python had a kid, who inherited Python's good looks and 8 | pleasant demeanor, along with C's confidence and athletic ability. 9 | 10 | 11 | What is Go? 12 | =========== 13 | 14 | Go is an open source, compiled, garbage-collected, concurrent system programming 15 | language. It was first designed and developed at Google Inc. beginning in 16 | September 2007 by Robert Griesemer, Rob Pike, and Ken Thompson. [#cit1]_ 17 | 18 | Minimalist 19 | ---------- 20 | 21 | The creators of Go advocate a minimalist approach to language design. This 22 | minimal elegance is often contrasted with the "kitchen sink" approach of C++. 23 | 24 | Opinionated 25 | ----------- 26 | 27 | Like Python, in Go there is often "one right way to do things", although that 28 | phrase is not so commonly used as in the Pythonist community. The compiler is 29 | renowed for its strictness. Things that would at most be warnings in other 30 | languages - e.g. unused imports, unused variables - are hard compiler errors in 31 | Go. At first that may seem like a draconian buzzkill - but soon you will begin 32 | to appreciate how clean and cruft-free it keeps your code. 33 | 34 | Fast 35 | ---- 36 | 37 | No question about it - Go is blazing fast. Despite a still young compiler with 38 | minimal speed optimizations, Go regularly scores at or near the top of 39 | inter-language benchmark comparisons. That's because Go is statically typed, 40 | compiled - and although garbage-collected, allows the programmer some degree of 41 | control over memory usage. 42 | 43 | Batteries Included 44 | ------------------ 45 | 46 | To a large degree Go follows Python's "batteries included" philosophy. Although 47 | there are not yet as many 3rd party libraries as there are for Python, 48 | nevertheless Go's standard library provides a solid foundation for many modern 49 | programming tasks. Built-in support for serving HTTP, de/serializing JSON, 50 | template rendering, and strong cryptography make Go ideal for modern web 51 | services development. 52 | 53 | Productive 54 | ---------- 55 | 56 | Go is frequently - and favorably - compared with Python and Ruby for programmer 57 | productivity. Its clean and elegant syntax, unobtrusive static typing, optional 58 | duck typing, batteries-included standard library, lighting-fast compiliation, 59 | and support for a variety of modern continuous integration tools make Go a 60 | productivity champion. 61 | 62 | 63 | Searching 64 | ========= 65 | 66 | Since "go" is such a common English word, it is completely useless as a search 67 | term when googling. Instead search for "golang". It is standard practice in 68 | the community that all Go-related blog posts, Github repos, tweets, job 69 | postings, etc be tagged with "golang". 70 | 71 | 72 | Who's Using Go? 73 | =============== 74 | 75 | Google 76 | Home of the Go authors and core team, signifiant parts of the Google 77 | infrastructure are thought to be written in Go. The company however does not 78 | publicly disclose which Google services are written in which languages. 79 | Youtube is known to be powered by Vitess_, an open source, massively scalable 80 | database multiplexing layer written in Go. 81 | 82 | Heroku 83 | Maintainers of the pq_ driver for PostgreSQL, significant parts of 84 | Heroku's infrastructure are said to be written in Go. One component that has 85 | been open sourced is Doozer_, a consistent distributed data store. 86 | 87 | Canonical 88 | The company behind Ubuntu Linux recently rewrote_ its Juju_ devops management 89 | application from Python to Go, with pleasing results. 90 | 91 | Soundcloud 92 | Internet music thought leaders SoundCloud use a bespoke build and deployment 93 | system called Bazooka_, designed to be a platform for managing the deployment 94 | of internal services. It is promised that Bazooka will be open sourced soon. 95 | 96 | Bitly 97 | Significant parts of Bitly_ are written in Go, including nsq_, a realtime 98 | distributed message processing system. 99 | 100 | Cloudflare 101 | Large volumes of internet traffic are served by Cloudflare's Railgun_ web 102 | optimization software, designed to speed up the delivery of content that 103 | cannot be cached. 104 | 105 | Iron.io 106 | Cloud infrastructure company and core Go community supporters Iron.io_ 107 | replaced parts of their Ruby codebase with Go, allowing them to handle a 108 | greater load with 2 workers than with 30 Ruby workers. 109 | 110 | TinkerCAD 111 | Cloud-based CAD application TinkerCAD_ is written in Go. 112 | 113 | Drone.io 114 | Continuous integration service Drone.io_ is written in Go. 115 | 116 | 117 | Background Assumptions 118 | ====================== 119 | 120 | * Familiarity with Python or a similar dynamic, interpreted language. 121 | * Comfortable working on the UNIX command line. 122 | * Basic understanding of internet protocols such as HTTP(S). 123 | 124 | 125 | Requirements 126 | ============ 127 | 128 | Command line examples were written on an `Ubuntu`_ 12.10 desktop environment. 129 | Everything we do in this book can also be done on other flavors of Linux, on Mac 130 | OSX - probably even on Windows. 131 | 132 | In addition to Go language basics, this book also covers cloud_ deployment and 133 | `continuous integration`_ tools & techniques popular in the Go community. You 134 | will need free accounts on the following services: 135 | 136 | * Github_ 137 | * Drone_ 138 | * Coveralls_ 139 | * Heroku_ 140 | 141 | 142 | Further Reading 143 | =============== 144 | 145 | * `Effective Go`_ by the creators of the language. Perhaps the single most 146 | valuable documentation resource for Go programmers. 147 | * `An Introduction to Programming in Go`_ by Caleb Doxsey 148 | * `Go for Pythonists`_ by Aditya Mukurjee 149 | 150 | 151 | 152 | 153 | .. _Vitess: https://code.google.com/p/vitess/ 154 | .. _pq: https://github.com/lib/pq 155 | .. _Doozer: https://github.com/ha/doozerd 156 | .. _rewrote: https://www.youtube.com/watch?v=USr0Bvg1ZOo 157 | .. _Juju: https://juju.ubuntu.com/ 158 | .. _Bazooka: http://backstage.soundcloud.com/2012/07/go-at-soundcloud/ 159 | .. _Bitly: http://word.bitly.com/post/29550171827/go-go-gadget 160 | .. _nsq: https://github.com/bitly/nsq 161 | .. _Railgun: http://blog.cloudflare.com/go-at-cloudflare 162 | .. _Iron.io: http://blog.iron.io/2013/03/how-we-went-from-30-servers-to-2-go.html 163 | .. _Drone.io: https://groups.google.com/forum/#!topic/golang-nuts/Lo7KP3rWP3o 164 | .. _TinkerCAD: http://www.youtube.com/watch?v=JE17r3n1kz4 165 | .. _Ubuntu: http://www.ubuntu.com 166 | .. _`Effective Go`: http://golang.org/doc/effective_go.html 167 | .. _`An Introduction to Programming in Go`: http://www.golang-book.com/ 168 | .. _`Go for Pythonists`: https://github.com/ChimeraCoder/go-for-pythonists 169 | .. _`Programming in Go: An Introduction`: http://programming-in-go.readthedocs.org 170 | .. _`continuous integration`: https://en.wikipedia.org/wiki/Continuous_integration 171 | .. _cloud: http://en.wikipedia.org/wiki/Cloud_computing 172 | .. _Github: http://github.com 173 | .. _Drone: http://drone.io 174 | .. _Coveralls: http://coveralls.io 175 | .. _Heroku: http://heroku.com 176 | 177 | 178 | .. rubric:: Citations 179 | 180 | .. [#cit1] https://en.wikipedia.org/wiki/Go_(programming_language) 181 | -------------------------------------------------------------------------------- /source/layout.rst: -------------------------------------------------------------------------------- 1 | ************** 2 | Project Layout 3 | ************** 4 | 5 | Just as ``$PYTHONPATH`` controls where the Python interpreter will look for 6 | source files, ``$GOPATH`` controls where the Go compiler and tools will look for 7 | source code. 8 | 9 | 10 | Hello World 11 | =========== 12 | 13 | Let us consider a modified version of the standard "Hello World" program. Our 14 | example will consist of a library package and an application package. The 15 | library exports one function, which returns the string "Hello world, the time 16 | is: " plus the current time. The application package calls the library 17 | function, and prints the hello message to the console. 18 | 19 | 20 | Python 21 | ------ 22 | 23 | 24 | In Python we might have a file layout like this:: 25 | 26 | $PYTHONPATH/ 27 | hello.py 28 | greeter.py 29 | 30 | The library package is contained in ``greeter.py``: 31 | 32 | .. literalinclude:: examples/python/hello/greeter.py 33 | :linenos: 34 | :lines: 5- 35 | 36 | The application is contained in ``hello.py``: 37 | 38 | .. literalinclude:: examples/python/hello/hello.py 39 | :linenos: 40 | :lines: 1,6- 41 | 42 | 43 | We run the Python application like this: 44 | 45 | .. code-block:: console 46 | 47 | $ python hello.py 48 | Hello world, the time is: Mon Jul 8 19:16:40 2013 49 | 50 | 51 | Go 52 | -- 53 | 54 | The "standard" layout for Go code is more complex than that for Python code. 55 | The disadvantage is that setup is slightly more work. The upside is a 56 | well-structured codebase that encourages modular code and keeps things orderly 57 | as a project grows in size. 58 | 59 | 60 | Typically Go code is developed using `distributed version control systems`_ like 61 | Git_ or Mercurial_. Therefore import paths are conventionally named based on 62 | the Github etc URL. The Go toolchain is aware of this, and can gracefully 63 | handle automatic dependency installation if your project conforms to the 64 | convention. 65 | 66 | Imagine for a moment we have created a Github repository named ``hello`` for our 67 | Hello World example. We would create a file layout like this:: 68 | 69 | $GOPATH/ 70 | src/ 71 | github.com/ 72 | jmcvetta/ 73 | hello/ 74 | hello.go 75 | greeter/ 76 | greeter.go 77 | 78 | The library is located in ``greeter.go``. Note the package name, ``greeter``, 79 | is the same as the name of the containing folder. This is mandatory. The 80 | package imports ``time`` from the standard library. 81 | 82 | 83 | .. literalinclude:: examples/go/hello/src/github.com/jmcvetta/hello/greeter/greeter.go 84 | :language: go 85 | :linenos: 86 | :lines: 5- 87 | 88 | The application is in ``hello.go``. This file declares its package as ``main``, 89 | and defines a ``main()`` function. This tells the compiler to generate an 90 | executable from the file. The package imports ``fmt`` from the standard 91 | library, and our ``greeter`` package specified by its path. 92 | 93 | .. literalinclude:: examples/go/hello/src/github.com/jmcvetta/hello/hello.go 94 | :language: go 95 | :linenos: 96 | :lines: 5- 97 | 98 | Functions imported from another package are *always* namespaced with the package 99 | name. In this case, we call ``greeter.Greeting()``. Go intentionally has no 100 | equivalent of Python's ``from some_package import *``. 101 | 102 | We can build the application with the ``go build`` command: 103 | 104 | .. code-block:: console 105 | 106 | $ go build -v 107 | github.com/jmcvetta/hello/greeter 108 | github.com/jmcvetta/hello 109 | 110 | $ ls 111 | greeter/ hello* hello.go 112 | 113 | $ ./hello 114 | Hello world, the time is: 2013-07-08 19:49:39.946836748 -0700 PDT 115 | 116 | 117 | .. _`distributed version control systems`: https://en.wikipedia.org/wiki/Distributed_revision_control 118 | .. _Git: http://git-scm.com/ 119 | .. _Mercurial: http://mercurial.selenic.com/ 120 | 121 | 122 | Dependencies 123 | ============ 124 | 125 | The ``go`` tool can automatically install dependencies. They are installed in 126 | the same URL-derived folder heirarchy alongside your code. 127 | 128 | Let's embelish our ``Greeting()`` function by making it return the current 129 | ``PATH`` as well. Although this could be done using nothing but the standard 130 | library, for purpose of instruction we will use the popular env_ package. 131 | 132 | .. literalinclude:: examples/go/hello_deps/src/github.com/jmcvetta/hello/greeter/greeter.go 133 | :language: go 134 | :linenos: 135 | :lines: 5- 136 | 137 | We can automatically install our new dependency with the ``go get`` command: 138 | 139 | .. code-block:: console 140 | 141 | $ go get -v . 142 | github.com/darkhelmet/env (download) 143 | github.com/darkhelmet/env 144 | github.com/jmcvetta/hello/greeter 145 | github.com/jmcvetta/hello 146 | 147 | Now we the ``env`` package installed, and our file system looks like:: 148 | 149 | $GOPATH/ 150 | src/ 151 | github.com/ 152 | darkhelmet/ 153 | env/ 154 | env.go 155 | env_test.go 156 | format.bash 157 | LICENSE.md 158 | README.md 159 | jmcvetta/ 160 | hello/ 161 | hello.go 162 | greeter/ 163 | greeter.go 164 | 165 | 166 | We can try out our new Hello World with the ``go run`` command, which build the application then runs it. 167 | 168 | .. code-block:: console 169 | 170 | $ go run hello.go 171 | Hello world, the time is 2013-07-08 20:36:31.496236239 -0700 PDT and your PATH is /home/jason/.rvm/gems/ruby-1.9.2-p320/bin:/home/jason/.rvm/gems/ruby-1.9.2-p320@global/bin:/home/jason/.rvm/rubies/ruby-1.9.2-p320/bin:/home/jason/.rvm/bin:/usr/local/heroku/bin:/usr/lib/lightdm/lightdm:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/home/jason/opt/bin:/home/jason/.scripts:/home/jason/opt/go/bin:/home/jason/work/go/bin:/home/jason/.rvm/bin 172 | 173 | 174 | 175 | .. _env: https://github.com/darkhelmet/env 176 | -------------------------------------------------------------------------------- /source/setup.rst: -------------------------------------------------------------------------------- 1 | ******************** 2 | Installation & Setup 3 | ******************** 4 | 5 | Installing Go 6 | ============= 7 | 8 | The first thing we need is a working Go installation on our system. The 9 | following instructions were derived from the official `Getting Started`_ documentation. 10 | 11 | Binary Packages 12 | --------------- 13 | 14 | Binary distributions of Go are available for the FreeBSD, Linux, Mac OS X, 15 | NetBSD, and Windows operating systems from the `official downloads page`_. 16 | 17 | 18 | Building from Source 19 | -------------------- 20 | 21 | Many developers prefer to install Go directly from the source code. Building is 22 | easy and quick - the Go compiler and tool chain can be compiled in a matter of 23 | minutes on even a modest workstation or laptop. 24 | 25 | 26 | Install Build Tools 27 | ^^^^^^^^^^^^^^^^^^^ 28 | 29 | The Go tool chain is written in C. To build it, you need a C compiler installed. 30 | You will also need the Mercurial DVCS tool to download the source. On Ubuntu run 31 | the following command to install the necessary packages: 32 | 33 | .. code-block:: console 34 | 35 | $ sudo apt-get install gcc libc6-dev mercurial 36 | 37 | See `Installing Go from source`_ and `Install C tools`_ for build instructions 38 | on other platforms. 39 | 40 | Fetch the repository 41 | ^^^^^^^^^^^^^^^^^^^^ 42 | 43 | Go will install to a directory named ``go``. Change to the directory that will 44 | be its parent and make sure the ``go`` directory does not exist. Then check out 45 | the repository: 46 | 47 | .. code-block:: console 48 | 49 | $ hg clone -u release https://code.google.com/p/go 50 | 51 | Build Go 52 | ^^^^^^^^ 53 | 54 | To build the Go distribution, run 55 | 56 | .. code-block:: console 57 | 58 | $ cd go/src 59 | $ ./all.bash 60 | 61 | If all goes well, it will finish by printing output like:: 62 | 63 | ALL TESTS PASSED 64 | 65 | --- 66 | Installed Go for linux/amd64 in /home/you/go. 67 | Installed commands in /home/you/go/bin. 68 | *** You need to add /home/you/go/bin to your $PATH. *** 69 | 70 | where the details on the last few lines reflect the operating system, 71 | architecture, and root directory used during the install. 72 | 73 | 74 | Environment Variables 75 | ===================== 76 | 77 | These instructions assume Go is installed at ``~/go``. If you installed 78 | elsewhere, change the commands to reflect your actual installation path. 79 | 80 | The Go tools look for several environment variables. Typically these are set in 81 | your shell profile. If you are using Bash, add the following lines to your 82 | ``~/.bashrc``:: 83 | 84 | export GOBIN=~/go/bin 85 | export GOARCH=amd64 86 | export GOOS=linux 87 | export GOROOT=~/go 88 | 89 | 90 | PATH 91 | ---- 92 | 93 | You probably also want to add the path to your ``go/bin`` directory to your ``PATH``:: 94 | 95 | export PATH=$PATH:/home/you/go/bin 96 | 97 | Reload your ``~/.bashrc`` file to active the new environment variables. Once 98 | the ``go`` binary is on your ``PATH``, you can confirm your install is working 99 | correctly by running the ``go version`` command. 100 | 101 | .. code-block:: console 102 | 103 | $ go version 104 | go version go1.1.1 linux/amd64 105 | 106 | 107 | GOPATH 108 | ------ 109 | 110 | The ``GOPATH`` environment variable is used to specify directories outside of 111 | ``$GOROOT`` that contain Go source code. Typically ``GOPATH`` is set to the 112 | root of a workspace. 113 | 114 | See :doc:`Project Layout ` for more detail. 115 | 116 | 117 | Intellij IDE 118 | ============ 119 | 120 | Go bindings are available for many popular programming editors and IDEs. As Go 121 | is still a relatively young language, none of these bindings are as 122 | full-featured as those for a mature language like Java. However a good 123 | `integrated development environment`_, even if not perfect, is still a valuable 124 | tool. 125 | 126 | Currently (July 2013) the IDE with the best Go support is `Intellij IDEA`_. 127 | 128 | 129 | Download 130 | -------- 131 | 132 | Download the Free community edition of Intellij IDEA appropriate for your 133 | platform from the official `download page`_. 134 | 135 | Untar the downloaded tarball, descend into the resulting folder, and start 136 | Intellij by running: 137 | 138 | .. code-block:: console 139 | 140 | $ ./bin/idea.sh 141 | 142 | 143 | Install Go Plugin 144 | ----------------- 145 | 146 | Open the Settings window (``File -> Settings``) and go to ``Plugins`` under 147 | ``IDE Settings``. Click on ``Browse repositories``, and type "golang" into the 148 | search form. There should be only one result, "golang.org support". 149 | Double-click on it to install, and close the settings. You will be prompted to 150 | restart Intellij. 151 | 152 | If you like vi-keys, you may also wish to install the ``IdeaVim`` plugin. 153 | 154 | 155 | 156 | .. _`Getting Started`: http://golang.org/doc/install 157 | .. _`official downloads page`: https://code.google.com/p/go/downloads/list 158 | .. _`Installing Go from source`: http://golang.org/doc/install/source 159 | .. _`Install C tools`: https://code.google.com/p/go-wiki/wiki/InstallFromSource#Install_C_tools 160 | .. _`integrated development environment`: https://en.wikipedia.org/wiki/Integrated_development_environment 161 | .. _`Intellij IDEA`: https://www.jetbrains.com/idea/ 162 | .. _`download page`: https://www.jetbrains.com/idea/download/ 163 | -------------------------------------------------------------------------------- /source/toolchain.rst: -------------------------------------------------------------------------------- 1 | **************** 2 | The Go Toolchain 3 | **************** 4 | 5 | Go is a compiled language - the source code you write must be converted to a 6 | binary format understandable to a computer before it is executed. The compiler 7 | is accessed through the ``go`` command. In addition, the ``go`` command 8 | provides several other tools 9 | 10 | The sections below describe several of the more popular ``go`` commands, but do 11 | not cover the complete set. For full information run: 12 | 13 | .. code-block:: console 14 | 15 | $ go help 16 | 17 | 18 | 19 | ``go build`` 20 | ============ 21 | 22 | Build compiles the packages named by the import paths, along with their 23 | dependencies, but it does not install the results. 24 | 25 | If the arguments are a list of .go files, build treats them as a list of source 26 | files specifying a single package. 27 | 28 | When the command line specifies a single main package, build writes the 29 | resulting executable to output. Otherwise build compiles the packages but 30 | discards the results, serving only as a check that the packages can be built. 31 | 32 | .. code-block:: console 33 | 34 | $ go build somefile.go # Build just this one file 35 | $ go build # Build package in current folder 36 | 37 | 38 | godoc.org 39 | --------- 40 | 41 | The website godoc.org_ extracts and displays automatic documentation, much like 42 | the ``godoc`` command, for any open source Go module specified by its import URL. 43 | 44 | See :doc:`GoDoc.org ` for more detail. 45 | 46 | 47 | 48 | .. _godoc.org: http://godoc.org 49 | .. _gowalker.org: http://gowalker.org --------------------------------------------------------------------------------