19. The Parable of the
Microsoft Engineer
Saturday, March 12, 2011
20. The Parable of the
Microsoft Engineer
It looks like you’re shooting
a target.
Would you like help?
Get help with shooting
the target
Just shoot the target
without help
Don’t show me this tip
again
Saturday, March 12, 2011
21. The Parable of the
Microsoft Engineer
It looks like you’re shooting
a target.
Would you like help?
Get help with shooting
the target
Just shoot the target
without help
Don’t show me this tip
again
Saturday, March 12, 2011
22. The Parable of the
Microsoft Engineer
It looks like you’re shooting
a target.
Would you like help?
Get help with shooting
the target
Just shoot the target
without help
Don’t show me this tip
again
Saturday, March 12, 2011
23. The Parable of the
Microsoft Engineer
Saturday, March 12, 2011
33. Have a default
Sphinx setup
Include your favorite template or theme
Saturday, March 12, 2011
34. Have a default
Sphinx setup
Customize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))
import $$$$PROJECT$$$$
os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'
copyright = u'2010, The Washington Times'
# The short X.Y version.
version = $$$$PROJECT$$$$.get_version()
# The full version, including alpha/beta/rc tags.
release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
35. Have a default
Sphinx setup
Customize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))
import $$$$PROJECT$$$$
os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'
copyright = u'2010, The Washington Times'
# The short X.Y version.
version = $$$$PROJECT$$$$.get_version()
# The full version, including alpha/beta/rc tags.
release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
36. Have a default
Sphinx setup
Customize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))
import $$$$PROJECT$$$$
os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'
copyright = u'2010, The Washington Times'
# The short X.Y version.
version = $$$$PROJECT$$$$.get_version()
# The full version, including alpha/beta/rc tags.
release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
37. Have a default
Sphinx setup
Customize the conf.py
import sys, os
sys.path.append(os.path.abspath('..'))
import $$$$PROJECT$$$$
os.environ['DJANGO_SETTINGS_MODULE'] = 'example.settings'
extensions = ['sphinx.ext.autodoc']
project = u'django-$$$$PROJECT$$$$'
copyright = u'2010, The Washington Times'
# The short X.Y version.
version = $$$$PROJECT$$$$.get_version()
# The full version, including alpha/beta/rc tags.
release =$$$$PROJECT$$$$.get_version()
Saturday, March 12, 2011
38. Have a default
Sphinx setup
Create placeholder and boilerplate files
doc_src
_build
_static
_templates
conf.py
getting_started.rst
index.rst
installation.rst
Saturday, March 12, 2011
39. Have a default
Sphinx setup
Modify Makefile to render HTML elsewhere
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
DESTDIR = ..
...
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs
@echo
@echo "Build finished. The HTML pages are in $(DESTDIR)/
docs."
Saturday, March 12, 2011
40. Have a default
Sphinx setup
Modify Makefile to render HTML elsewhere
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
DESTDIR = ..
...
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs
@echo
@echo "Build finished. The HTML pages are in $(DESTDIR)/
docs."
Saturday, March 12, 2011
41. Have a default
Sphinx setup
Modify Makefile to render HTML elsewhere
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
DESTDIR = ..
...
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DESTDIR)/docs
@echo
@echo "Build finished. The HTML pages are in $(DESTDIR)/
docs."
Saturday, March 12, 2011
42. Have a default
Sphinx setup
Allows you to build docs often
Saturday, March 12, 2011
43. Have a default
Sphinx setup
Allows you to build docs often
Saturday, March 12, 2011
44. Have a default
Sphinx setup
See http://github.com/washingtontimes/
django-app-skeleton/
Saturday, March 12, 2011
45. Jumping off points
http://www.flickr.com/photos/frecklefinger/1369581228/
Saturday, March 12, 2011
46. Feature Lists
.. _feature_list:
Feature List
============
* Tags - Using `django tagging <http://code.google.com/p/django-
tagging/>`_
* Groups
* Public
* Private
* Corp only
* Alliance only
* Export
* xml
* copy & paste
* `eve dna <http://wiki.eveonline.com/en/wiki/Ship_DNA>`_
* Ratings - Up/Down ratting system
* `django critic <https://github.com/washingtontimes/django-
critic>`_
* Disqus Comments
* Favorite fittings
* Fork Fittings
* Version Fittings
* Rss/Atom
Saturday, March 12, 2011
47. Feature Lists
.. _feature_list:
Feature List
============
How do you add the tags?
* Tags - Using `django tagging <http://code.google.com/p/django-
How do you browse the tags?
tagging/>`_
* Groups
* Public
* Private
* Corp only
* Alliance only
* Export
* xml
* copy & paste
* `eve dna <http://wiki.eveonline.com/en/wiki/Ship_DNA>`_
* Ratings - Up/Down ratting system
* `django critic <https://github.com/washingtontimes/django-
critic>`_
* Disqus Comments
* Favorite fittings
* Fork Fittings
* Version Fittings
* Rss/Atom
Saturday, March 12, 2011
48. Feature Lists
.. _feature_list:
Feature List
============
* Tags - Using `django tagging <http://code.google.com/p/django-
tagging/>`_
* Groups
* Public
* Private
* Corp only
* Alliance only
* Export
* xml
* copy & paste
* `eve dna <http://wiki.eveonline.com/en/wiki/Ship_DNA>`_
* Ratings - Up/Down ratting system
* `django critic <https://github.com/washingtontimes/django-
critic>`_ How do you fork the fittings?
* Disqus Comments
How do see who has forked your fittings?
* Favorite fittings
What happens if they fork your mom?
* Fork Fittings
* Version Fittings
* Rss/Atom
Saturday, March 12, 2011
49. Flushing out the
initial feature list led
to this much
documentation
Saturday, March 12, 2011
50. Flushing out the
initial feature list led
to this much
documentation
Saturday, March 12, 2011
51. Examples of how features
will work are flushed out
Saturday, March 12, 2011
55. Next Step: Write some step-by-
step instructions
Saturday, March 12, 2011
56. Rough notes
Starting Out
1. Create a documentation storage record (it configures and sets up a repository)
Name, Repository Type (git, hg), remote, url prefix, etc.
2. Optional: Import a zipped sphinx documentation directory
3. Configure Sphinx Settings
Initially it will have to be the editing of a python file until better ways can be devised.
That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the Documentation
Sphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of
documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.
Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for
every level of the URL structure. So
* Directories/Folders/Table of Contents are referenced at URLs ending with a /
* Pages are referenced by URLs ending without a /
In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://
www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page:
1. A directory is created and the page is saved in it.
2. An index.rst file is created in the directory and the page is added to its toctree listing.
3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage
1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved.
2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item.
3. subsection1/index is added to the toctree of the section1/index.rst file.
You can edit the index.rst file by going to either the directory URL (/docs/getting_started/) or the index URL (/
docs/getting_started/index) and editing the page.
If you remove an item from the toctree Sphwiki will add it back in the next time you edit that page.
You can re-order the items without any problems. Sphwiki only looks for the page's existence within the toctree.
Creating a New Page
1. Make sure you are logged in, if necessary.
2. Go to the URL of the new page
3. You will be prompted that the page doesn't exist, do you want to create it?
4. Say Yes.
5. Start writing.
Saturday, March 12, 2011
57. Rough notes
Starting Out
1. Create a documentation storage record (it configures and sets up a repository)
Name, Repository Type (git, hg), remote, url prefix, etc.
2. Optional: Import a zipped sphinx documentation directory
3. Configure Sphinx Settings
Initially it will have to be the editing of a python file until better ways can be devised.
That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the Documentation
Sphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of
documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.
Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for
every level of the URL structure. So
* Directories/Folders/Table of Contents are referenced at URLs ending with a /
* Pages are referenced by URLs ending without a /
In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://
www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page:
1. A directory is created and the page is saved in it.
2. An index.rst file is created in the directory and the page is added to its toctree listing.
3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage
1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved.
2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item.
3. subsection1/index is added to the toctree of the section1/index.rst file.
Saturday, March 12, 2011
58. Rough notes
Starting Out
1. Create a documentation storage record (it configures and sets up a repository)
Name, Repository Type (git, hg), remote, url prefix, etc.
2. Optional: Import a zipped sphinx documentation directory
3. Configure Sphinx Settings
Initially it will have to be the editing of a python file until better ways can be devised.
That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the Documentation
Sphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of
documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.
Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for
every level of the URL structure. So
* Directories/Folders/Table of Contents are referenced at URLs ending with a /
* Pages are referenced by URLs ending without a /
In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://
www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page:
1. A directory is created and the page is saved in it.
2. An index.rst file is created in the directory and the page is added to its toctree listing.
3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage
1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved.
2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item.
3. subsection1/index is added to the toctree of the section1/index.rst file.
Saturday, March 12, 2011
59. That's it! Now the table of contents is served at http://sitename.com/prefix/
Structure of the Documentation
Rough notes
Sphinx keeps track of files using a table of contents structure called a toctree. The toctree is simply a listing of
documents (including documents that have their own toctrees). toctrees are typically in a file named index.rst.
Sphwiki maintains a directory structure by adding (if one doesn't exist) and maintaining an index.rst file for
every level of the URL structure. So
* Directories/Folders/Table of Contents are referenced at URLs ending with a /
* Pages are referenced by URLs ending without a /
In otherwords, http://www.example.com/docs/getting_started/ is really the same as http://
www.example.com/docs/getting_started/index
When you first create a page within a subdirectory, three things are done when you save the page:
1. A directory is created and the page is saved in it.
2. An index.rst file is created in the directory and the page is added to its toctree listing.
3. An item is added to the index.rst of the directory's parent
For example, if you create the new page section1/subsection1/newpage
1. A directory named subsection1 is created within the section1 directory, and newpage.rst is saved.
2. An index.rst page is created within the subsection1 directory and newpage is added under thetoctree item.
3. subsection1/index is added to the toctree of the section1/index.rst file.
You can edit the index.rst file by going to either the directory URL (/docs/getting_started/) or the index URL (/
docs/getting_started/index) and editing the page.
If you remove an item from the toctree Sphwiki will add it back in the next time you edit that page.
You can re-order the items without any problems. Sphwiki only looks for the page's existence within the toctree.
Creating a New Page
1. Make sure you are logged in, if necessary.
2. Go to the URL of the new page
3. You will be prompted that the page doesn't exist, do you want to create it?
4. Say Yes.
5. Start writing.
Saturday, March 12, 2011
63. In summary
• Code your documentation
• Make a customized documentation skeleton
• Iterate over your documentation
• Find a groove that works for you
Saturday, March 12, 2011
64. Thank You
• Corey Oordt
• coreyoordt@gmail.com
• http://github.com/coordt
• http://github.com/washingtontimes
• @coordt
Saturday, March 12, 2011