From 6a1682e6816b81636105d4c872490ac732c6aab6 Mon Sep 17 00:00:00 2001 From: Daniel Chen Date: Sat, 7 Feb 2015 18:42:50 -0500 Subject: [PATCH 1/4] beginning of post that introduces other parts --- .../2015-02-05-open-sourcing-a-python-project-II.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 _posts/2015-02-05-open-sourcing-a-python-project-II.md diff --git a/_posts/2015-02-05-open-sourcing-a-python-project-II.md b/_posts/2015-02-05-open-sourcing-a-python-project-II.md new file mode 100644 index 0000000..2ef986b --- /dev/null +++ b/_posts/2015-02-05-open-sourcing-a-python-project-II.md @@ -0,0 +1,12 @@ +--- +layout: post +title: "Open Source A Python Project II: Documentation" +date: 2015-02-07 +categories: opensource python documentation sphinx readthedocs +--- + +- In [part I]() I introduced my [project]() and some of the initial hurdles. +- In this section I describe documenting your code using [sphinx]() and +publishing the documentation on to [Read the Docs](). +- In [part III]() I describe how to setup a package for PyPI. + From cd08088c55b0702308849d5cca0d77b651f02c72 Mon Sep 17 00:00:00 2001 From: Daniel Chen Date: Sun, 8 Feb 2015 12:18:20 -0500 Subject: [PATCH 2/4] categories is Tutorials and put old cats under tags --- _posts/2015-02-05-open-sourcing-a-python-project-II.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/_posts/2015-02-05-open-sourcing-a-python-project-II.md b/_posts/2015-02-05-open-sourcing-a-python-project-II.md index 2ef986b..89f5817 100644 --- a/_posts/2015-02-05-open-sourcing-a-python-project-II.md +++ b/_posts/2015-02-05-open-sourcing-a-python-project-II.md @@ -2,7 +2,13 @@ layout: post title: "Open Source A Python Project II: Documentation" date: 2015-02-07 -categories: opensource python documentation sphinx readthedocs +categories: Tutorials + +tags: + - opensource + - python + - sphinx + - read the docs --- - In [part I]() I introduced my [project]() and some of the initial hurdles. From 9a4de7796461fb29aaf25c849d3dc18a5af08ff4 Mon Sep 17 00:00:00 2001 From: Daniel Chen Date: Sun, 8 Feb 2015 12:18:34 -0500 Subject: [PATCH 3/4] draft Sphinx and RTD setup --- ...02-05-open-sourcing-a-python-project-II.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/_posts/2015-02-05-open-sourcing-a-python-project-II.md b/_posts/2015-02-05-open-sourcing-a-python-project-II.md index 89f5817..41564ef 100644 --- a/_posts/2015-02-05-open-sourcing-a-python-project-II.md +++ b/_posts/2015-02-05-open-sourcing-a-python-project-II.md @@ -16,3 +16,71 @@ tags: publishing the documentation on to [Read the Docs](). - In [part III]() I describe how to setup a package for PyPI. +tl;dr: + +` sphinx-apidoc -F -o docs NAME_OF_FOLDER`. + +Thanks to [Jeff Knupp](http://www.jeffknupp.com/) and his +'[Open Sourcing a Python Project the Right Way](http://www.jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/)'. +post. + +Don't make the mistake I did when +I was kinkering with a throwaway [example]() -- I put hyphens in the folder +name. It will cause a lot of [problems](), use under_scores instead (or +better yet, pick a one-word module name). +If you tried to import a Python module with a hyphen, +it will cause problems within Python that will prompt you to use underscores, +so in practice, you shouldn't have the same problems as I did. + +Take a look at the Python Sphinx [example](), and use it as a reference +on how to write a docstring. Essentially there are two ways you can write them: + +like this: + +```python +def my_function(arg1 arg2): + pass +``` + +or like this: +```python +def my_function(arg1 arg2): + pass +``` + +# Sphinx + +Once you have your code ready, you have to actully 'install' the module (I +discuss this at [Part I Importing Modules]()), otherwise sphinx won't really +see the actual code in the module, you'll end up with a list of module names +with no function definitions or documentation. + +When you have the module installed you run: + +` sphinx-apidoc -F -o docs NAME_OF_FOLDER` + +It will create a `docs` folder in the root project directory. At this point +you should be ready for [Read the Docs](), but if you want to view it locally, +go into the `docs` folder, and build the documentation by typing: + +`make html` + +if you want an html documentation. There are other formats if you look at the +`makefile`, if you type `make` it will prompt you for a format as well. + +The output of the `make` will be under the `_build/` and, in this case `html/`. +There will be an `index.html` file that will show you what the documentation +will look like in Sphinx or if you upload it to PyPI. + +# Read the Docs +Once you see Sphinx is building correctly, you should be ready to point your +repository to [Read the Docs](). The official setup documentation is +[here](), +but esseentailly, create an account, link it to your +[github]() account, +and have RTD track the repository that you are working on. +Make sure when you are setting up the RTD, under advanced settings, be sure +to use to dropdown menu and select `Sphinx Documentaiton`. I believe the +default would be something along the lines of `markdown`. +After that is all set, every push you make will cause RTD to rebuild the +documentation. From ba8bf7a0de463f325a1c0bb30afa660ee0d2ef63 Mon Sep 17 00:00:00 2001 From: Daniel Chen Date: Mon, 9 Feb 2015 16:13:15 -0500 Subject: [PATCH 4/4] added notes to self about what to select in the RTD advanced menu --- _posts/2015-02-05-open-sourcing-a-python-project-II.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/_posts/2015-02-05-open-sourcing-a-python-project-II.md b/_posts/2015-02-05-open-sourcing-a-python-project-II.md index 41564ef..3df49c0 100644 --- a/_posts/2015-02-05-open-sourcing-a-python-project-II.md +++ b/_posts/2015-02-05-open-sourcing-a-python-project-II.md @@ -20,7 +20,7 @@ tl;dr: ` sphinx-apidoc -F -o docs NAME_OF_FOLDER`. -Thanks to [Jeff Knupp](http://www.jeffknupp.com/) and his +Thanks to [Jeff Knupp](http://www.jeffknupp.com/) and his '[Open Sourcing a Python Project the Right Way](http://www.jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/)'. post. @@ -80,7 +80,9 @@ but esseentailly, create an account, link it to your [github]() account, and have RTD track the repository that you are working on. Make sure when you are setting up the RTD, under advanced settings, be sure -to use to dropdown menu and select `Sphinx Documentaiton`. I believe the -default would be something along the lines of `markdown`. +to use to dropdown menu and select `Sphinx HTML`. I believe the +default would be something along the lines of `Automatically Choose`. After that is all set, every push you make will cause RTD to rebuild the documentation. + +Select `Python` under Programming Language