Python documentation - Revision history

Admin: /* Sphinx */

2016-07-15T05:41:15Z

Sphinx

← Older revision		Revision as of 05:41, 15 July 2016
Line 76:		Line 76:
	==Sphinx==		==Sphinx==

	Sphinx is not automatically generated, ~~except when~~ you specifically instruct it to automatically generate documentation.		Sphinx is not automatically generated, by default - you must specifically instruct it to automatically generate documentation and include it. It makes your documentation much more customizable.

	Sphinx is cumbersome and requires you to learn yet another markup language. Sphinx adds bold and italic and small text and big text all over the place~~. Does not~~ look great ~~by default.~~		Sphinx is cumbersome and requires you to learn yet another markup language. Sphinx adds bold and italic and small text and big text all over the place, and doesn't look too great.

	~~My notes on [[Sphinx]] are at the [[Sphinx]] page~~.

	=Miscellaneous=		=Miscellaneous=

Admin: /* Sphinx */

2016-07-15T05:40:06Z

Sphinx

← Older revision		Revision as of 05:40, 15 July 2016
Line 78:		Line 78:
	Sphinx is not automatically generated, except when you specifically instruct it to automatically generate documentation.		Sphinx is not automatically generated, except when you specifically instruct it to automatically generate documentation.

	Sphinx is cumbersome and requires you to learn yet another markup language.		Sphinx is cumbersome and requires you to learn yet another markup language. Sphinx adds bold and italic and small text and big text all over the place. Does not look great by default.

	Sphinx ~~is ugly as hell (the automatically generated stuff, anyway), adding~~ bold and italic and small text and big text ~~like a drunken sailor with a font palate~~.

	My notes on [[Sphinx]] are at the [[Sphinx]] page.		My notes on [[Sphinx]] are at the [[Sphinx]] page.


	=Miscellaneous=		=Miscellaneous=

Admin: /* GitHub */

2016-07-15T05:39:06Z

GitHub

← Older revision		Revision as of 05:39, 15 July 2016
Line 56:		Line 56:
	This makes it worth learning - but it doesn't give you the detailed documentation that you get with Doxygen or epydoc.		This makes it worth learning - but it doesn't give you the detailed documentation that you get with Doxygen or epydoc.

	Also, if you are stuck with [[Svn]] this is kind of a dead end.		Also, if you are stuck with [[Svn]] <s>this is kind of a dead end</s> DUMP SVN ALREADY!!!

	Apparently you can turn sphinx documentation into GitHub documentation, although Sphinx is not a winning documentation solution: http://daler.github.io/sphinxdoc-test/includeme.html		Apparently you can turn sphinx documentation into GitHub documentation, although Sphinx is not a winning documentation solution: http://daler.github.io/sphinxdoc-test/includeme.html

Admin: /* GitHub */

2016-07-15T05:38:39Z

GitHub

← Older revision		Revision as of 05:38, 15 July 2016
Line 52:		Line 52:
	==GitHub==		==GitHub==

	GitHub uses the Markdown markup language~~, which is actually pretty~~ useful, ~~and it~~ looks ~~really good~~, ~~so it is worth learning. But it still isn't (necessarily) worth writing all of your documentation in GitHub's markup language~~.		GitHub uses the Markdown markup language: very useful, looks great, hosted for free.

	Also, if you ~~despise~~ [[~~Git~~]], this is kind of a dead end.		This makes it worth learning - but it doesn't give you the detailed documentation that you get with Doxygen or epydoc.

			Also, if you are stuck with [[Svn]] this is kind of a dead end.

	Apparently you can turn sphinx documentation into GitHub documentation, although Sphinx is not a winning documentation solution: http://daler.github.io/sphinxdoc-test/includeme.html		Apparently you can turn sphinx documentation into GitHub documentation, although Sphinx is not a winning documentation solution: http://daler.github.io/sphinxdoc-test/includeme.html

Admin: /* Doxygen */

2016-07-15T05:37:25Z

Doxygen

← Older revision		Revision as of 05:37, 15 July 2016
Line 48:		Line 48:
	==Doxygen==		==Doxygen==

	Doxygen is a breeze for automatically-generated documentation, and is source-centric. It isn't the ~~prettiest~~, but it ~~isn't a purple-assed baboon, either~~.		Doxygen is a breeze for automatically-generated documentation, and is source-centric. It isn't the best, but it could certainly look worse.

	==GitHub==		==GitHub==

Admin at 05:36, 15 July 2016

2016-07-15T05:36:41Z

← Older revision		Revision as of 05:36, 15 July 2016
Line 1:		Line 1:
	There are a couple of options for creating documentation in Python, particularly Python that is hosted somewhere like Github, each with different advantages/disadvantages.		There are a couple of options for creating documentation in Python, particularly Python that is hosted somewhere like Github, each with different advantages/disadvantages.

			<!--
	http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html		http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html
			-->

	=What I'm Looking For=		=What I'm Looking For=

Admin: /* What I'm Looking For */

2016-07-15T05:36:13Z

What I'm Looking For

← Older revision		Revision as of 05:36, 15 July 2016
Line 7:		Line 7:
	In order of importance, I want the following out of my documentation system:		In order of importance, I want the following out of my documentation system:

	'''Barely Sufficient ~~(read: I am lazy)~~''' - First, following [[10 Best]] practices for software engineering #5 (create barely-sufficient, source-centric documentation), ~~I want a~~ documentation ~~system that requires~~ minimal effort (anything more than that, and the documentation will always be out of date and will require too much effort).		'''Barely Sufficient''' - First, following [[10 Best]] practices for software engineering #5 (create barely-sufficient, source-centric documentation), documentation systems should require minimal effort (anything more than that, and the documentation will always be out of date and will require too much effort).

	'''Room For Expansion''' - However, if I have a surge of benevolence, I want a documentation system that will allow me to explain stuff using diagrams and/or equations.		'''Room For Expansion''' - However, if I have a surge of benevolence, I want a documentation system that will allow me to explain stuff using diagrams and/or equations.

	'''Pretty''' - Documentation should not look like a ~~purple-assed~~ baboon.		'''Pretty''' - Documentation should not look like a baboon.

	'''Not Require ~~Me To Learn Yet Another Markup~~ Language/Toolchain/Build System ~~(read: lazy)~~''' - ~~Unless it makes my documentation look really sexy, and there's absolutely no other way to do it, I don't want to have to learn yet another markup language, toolchain, and/or build system~~.		'''Not Require Learning New Language/Toolchain/Build System''' - life is too short.

	=The Options=		=The Options=

Admin: /* The Options */

2013-06-13T19:01:42Z

The Options

← Older revision		Revision as of 19:01, 13 June 2013
Line 18:		Line 18:

	I considered the following options:		I considered the following options:
			# Epydocs
	# Pydoc		# Pydoc
	# Docstrings		# Docstrings

Admin at 22:32, 10 June 2013

2013-06-10T22:32:47Z

← Older revision		Revision as of 22:32, 10 June 2013
Line 1:		Line 1:
	There are a couple of options for creating documentation in Python, particularly Python that is hosted somewhere like Github, each with different advantages/disadvantages.		There are a couple of options for creating documentation in Python, particularly Python that is hosted somewhere like Github, each with different advantages/disadvantages.

			http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html

	=What I'm Looking For=		=What I'm Looking For=

Admin at 15:21, 10 June 2013

2013-06-10T15:21:28Z

← Older revision		Revision as of 15:21, 10 June 2013
Line 25:		Line 25:
	=The Winners=		=The Winners=

	==~~Doxygen~~==		==Epydoc==

	Doxygen ~~is a breeze for automatically~~-~~generated documentation~~, ~~and is~~ source-centric~~. It isn't the prettiest, but it isn't a purple-assed baboon, either~~.		Epydoc creates [[Doxygen]]-esque output (win) using pydocs (also win), to accomplish source-centric documentation (see item 5 on [[10_Best_Practices_for_Software_Engineering]] page).

	==Doxypypy==		==Doxypypy==
Line 40:		Line 40:

	=The Not-Winners, Not-Losers=		=The Not-Winners, Not-Losers=

			==Doxygen==

			Doxygen is a breeze for automatically-generated documentation, and is source-centric. It isn't the prettiest, but it isn't a purple-assed baboon, either.

	==GitHub==		==GitHub==

	GitHub uses the Markdown markup language, which is actually pretty useful, and it looks really good, so it is worth learning. But it still isn't (necessarily) worth writing all of your documentation in GitHub's markup language.		GitHub uses the Markdown markup language, which is actually pretty useful, and it looks really good, so it is worth learning. But it still isn't (necessarily) worth writing all of your documentation in GitHub's markup language.

			Also, if you despise [[Git]], this is kind of a dead end.

	Apparently you can turn sphinx documentation into GitHub documentation, although Sphinx is not a winning documentation solution: http://daler.github.io/sphinxdoc-test/includeme.html		Apparently you can turn sphinx documentation into GitHub documentation, although Sphinx is not a winning documentation solution: http://daler.github.io/sphinxdoc-test/includeme.html