Adding initial skeleton for sphinx documentation project. Fixes T139
ClosedPublic
Actions

Authored by tflink on Apr 23 2014, 4:28 PM.

Details

Reviewers

kparal
mkrizek
jskladan

Maniphest Tasks

T139: Create skeleton sphinx project for libtaskotron

Summary

This is a set of initial documentation for libtaskotron. It still needs work and more content but it's ready for initial review.

Test Plan

This is just docs, so no real test plan.

Diff Detail

Branch

feature/T139-initial-sphinx-project

Lint

No Linters Available

Unit

No Unit Test Coverage

The rendered docs are available at:
http://tflink.fedorapeople.org/taskotron/initial-taskotron-docs/

docs/source/devguide.rst
50	The binary is called py.test, at least on my system.
54	Same as above.

I have proposed a few changes, but apart from that, I think it looks good. Thanks for working on this.

docs/source/devguide.rst
46	are not run as often That almost sounds like we run it only very occasionally. I think everyone should run the full functional test suite before pushing a patch. Can we rephrase it a bit? E.g. "They are often slower, but offer better test coverage."
79	Output redirection doesn't work with `sudo`. Use this instead: sudo curl http://repos.fedorapeople.org/repos/tflink/phabricator/fedora-phabricator.repo -o /etc/yum.repos.d/fedora-phabricator.repo Maybe `fedora-qa-phabricator.repo` would a better file name?
152	I have seen `arc` behaving very weirdly very often. Please recommend this command instead: arc diff develop Otherwise it sometimes ends up detecting wrong parent branches, creating new reviews instead of updating existing one, etc.
174	When using `arc diff develop`, I have never seen a problem in existing Differential Review detection. But `--update` obviously works as well. For problems mentioned above, I think `develop` should always be a part of the command: arc diff develop or arc diff develop --update DXXX
186–187	The problem with `arc land` is that it puts a lot of clutter into your commit message without your control and pushes immediately (you can use special cmdline options to avoid that). I think it's much better to use traditional: git checkout develop git merge --squash feature/TXXX git commit # remove all the clutter from the commit message, just keep in short summary and Differential link git push origin Alternatively, `git flow feature finish` can be used and then `git commit --amend` to remove the clutter.
205	`arcpatch-DXXX`
225–235	Would it make sense to copy this section to `readme.rst` in top-level directory?

Maybe fedora-qa-phabricator.repo would a better file name?

The differentiation was between fedora-phabricator and epel-phabricator, so I'm not sure fedora-qa-phabricator would make a whole lot of sense here. Then again, I did create the repo before we started patching the upstream sources. I don't see much of a benefit to changing that filename but I'm not hugely against it either.

> are not run as often
That almost sounds like we run it only very occasionally. I think everyone should run the full functional test suite before pushing a patch. Can we rephrase it a bit? E.g. "They are often slower, but offer better test coverage."

I'm usually running the unit tests at least every couple minutes when I'm writing code, so that interpretation didn't occur to me :)

re: arc land:
Yeah, suppose that there are better ways of doing that. Come to think of it, I usually use git flow feature finish myself. I don't really mind the 'noise' from arcanist, though. Do you really think that it needs to be cleaned up?

Would it make sense to copy this section to readme.rst in top-level directory?

It probably does, yes. I'll add the section.

updating to current develop branch
adding doc building instructions to readme, changing the title
fixing mistakes, clarifying unit tests and adding merge instructions to devguide to fix comments from review

I don't really mind the 'noise' from arcanist, though. Do you really think that it needs to be cleaned up?

I'm not really a fan of the Phab's idea that commit message == full review description. In my view, commit message should be concise and clear and link to the review ticket for further details. The review description should be the opposite, very detailed. Also, I usually raise some questions in it. The commit message should reflect the final decisions taken after the discussion in the review, not the questions. Look at D26, D39 or D52. Would you really like to have all of it in the commit message?

One minor annoyance is also the line length. When writing the review descriptions, I don't wrap lines, obviously, it's just a text in a web page. But if we end up with 200+ characters commit title or 500+ characters-wide lines in the commit body, it breaks the formatting in all the usual tools, like git log or git branch. Of course, it might be seen as a deficiency of those tools. But the git guidelines say that the commit title should not be longer than 50-80 chars (and vim notifies you of a longer title by showing red background for longer titles), so the situation is a bit different from e.g. email line wrapping, I think.

I can certainly live with it, but I don't think commit message should equal review request description and I personally always adjust it before pushing to origin.

docs/source/devguide.rst
192	I think that a squash merge is better, because who would like to see a number of "WIP" commits in the log? It makes operations on the history (e.g. navigating or bisecting) much harder. But that's just my personal preference.

I can certainly live with it, but I don't think commit message should equal review request description and I personally always adjust it before pushing to origin.

Any suggestions for what to use as a suggested template?

docs/source/devguide.rst
192	For that particular line, a squash merge is a really bad idea. That's just updating the feature branch from `develop`. For the actual merge into develop (with the `git flow feature finish`), I could go both ways. Personally, I think that the bigger problem is all the meaningless "WIP" commit messages but that being said, I usually rebase my feature branches before merging them in. Is using `--squash` trustworthy? I usually prefer to to my rebases by hand to make sure that it looks right before merging.

docs/source/devguide.rst
192	Oh, I misunderstood the line, sorry. In this case, `git merge develop` or `git rebase develop` makes sense, but the `--ff-only` never works, I believe. I tried locally on a trivial example and it didn't work.
193	Let's recommend this: If you want to push several commits (there are several no-nonsense logically separated commits): If the commits are not yet to your liking, run git rebase -i develop and adjust the commits. Then run git flow feature finish TXXX-some-feature If your feature can be nicely expressed in just a single commit, run: git flow feature finish --squash TXXX-some-feature (This should be identical approach to manually rebasing and squashing commits.)
194	Any suggestions for what to use as a suggested template? Before pushing, it's nice of you to make the commit message pretty. You can amend the latest commit message: git commit --amend and remove any unnecessary noise (Test Plan, Reviewers, CC, too detailed description) and wrap lines properly. Please keep the review hyperlink.

docs/source/devguide.rst
192	I guess the question becomes whether to suggest `merge` or `rebase`, then. I think that `rebase` could lead to cleaner history but `merge` would work in more situations. Any objections to suggesting `rebase` and say something like "if you run into problems, please ask for help"?
193	if we go that route, I'd prefer to specify a preferred default. Any objections to saying "a single commit per feature is preferred in most cases."?
194	Is that specific enough or should we have an example template?

Once you're satisfied with the small tweaks, please merge into develop. The important thing is that we have the sphinx config and doc build instructions. We can discuss and amend the guides any time in the future, let's not hold this review on this :) Thanks.

docs/source/devguide.rst
192	I have the same understanding as you do. No objections at all.
193	I completely agree. Most features are small changes and it's easiest to have them in a single commit.
194	Isn't that overkill? Just a quick look to `git log` will tell the person how the commit messages usually look like. We can also just say this ("Have a look at how commits usually look like") instead of enumerating things that can possibly be removed.

Fixed with rLTRNe18699f5452bc62aa73cd5a96c562c80722f4592

Revision Contents

		Path
M		.gitignore (2 lines)
A	M	docs/Makefile (153 lines)
A	M	docs/source/conf.py (242 lines)
A	M	docs/source/devguide.rst (355 lines)
A	M	docs/source/index.rst (47 lines)
A	M	docs/source/library.rst (25 lines)
M		readme.rst (21 lines)

Diff	ID	Base	Description	Created	Lint	Unit
Base			Base
Diff 1	183	9eb043e		Apr 23 2014, 4:28 PM	★	★
Diff 2	197	ff41db8	- updating to current develop branch	Apr 24 2014, 7:41 PM	★	★

Commit	Tree	Parents	Author	Summary	Date
a1415c6ed4d7	826f8b312da3	53763f9429bb	Tim Flink	fixing mistakes, clarifying unit tests and adding merge instructions to… (Show More…)	Apr 24 2014, 7:40 PM
53763f9429bb	7dc5cf643676	4898f6c42865	Tim Flink	adding doc building instructions to readme, changing the title	Apr 24 2014, 7:39 PM
4898f6c42865	c8e0f619a79d	76b467222ca6 ff41db8250e6	Tim Flink	Merge branch 'develop' into feature/T139-initial-sphinx-project	Apr 24 2014, 7:36 PM
76b467222ca6	e24e8947ba03	9eb043e95fc5	Tim Flink	Adding initial skeleton for sphinx documentation project. Fixes T139 (Show More…)	Apr 23 2014, 4:10 PM

Diff 197

View Options

.gitignore

Show All 31 Lines
32	# Translations	32	# Translations
33	*.mo	33	*.mo
34		34
35	# Complexity	35	# Complexity
36	output/*.html	36	output/*.html
37	output/*/index.html	37	output/*/index.html
38		38
39	# Sphinx	39	# Sphinx
40	docs/_build	40	docs/build
41		41
42	# Virtualenv	42	# Virtualenv
43	/env_taskotron/	43	/env_taskotron/

View Options

docs/Makefile

This file was added.

		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		# Internal variables.
		11		PAPEROPT_a4 = -D latex_paper_size=a4
		12		PAPEROPT_letter = -D latex_paper_size=letter
		13		ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
		14		# the i18n builder cannot share the environment and doctrees with the others
		15		I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
		16
		17		.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
		18
		19		help:
		20		@echo "Please use \`make <target>' where <target> 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 " latexpdf to make LaTeX files and run them through pdflatex"
		32		@echo " text to make text files"
		33		@echo " man to make manual pages"
		34		@echo " texinfo to make Texinfo files"
		35		@echo " info to make Texinfo files and run them through makeinfo"
		36		@echo " gettext to make PO message catalogs"
		37		@echo " changes to make an overview of all changed/added/deprecated items"
		38		@echo " linkcheck to check all external links for integrity"
		39		@echo " doctest to run all doctests embedded in the documentation (if enabled)"
		40
		41		clean:
		42		-rm -rf $(BUILDDIR)/*
		43
		44		html:
		45		$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
		46		@echo
		47		@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
		48
		49		dirhtml:
		50		$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
		51		@echo
		52		@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
		53
		54		singlehtml:
		55		$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
		56		@echo
		57		@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
		58
		59		pickle:
		60		$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
		61		@echo
		62		@echo "Build finished; now you can process the pickle files."
		63
		64		json:
		65		$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
		66		@echo
		67		@echo "Build finished; now you can process the JSON files."
		68
		69		htmlhelp:
		70		$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
		71		@echo
		72		@echo "Build finished; now you can run HTML Help Workshop with the" \
		73		".hhp project file in $(BUILDDIR)/htmlhelp."
		74
		75		qthelp:
		76		$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
		77		@echo
		78		@echo "Build finished; now you can run "qcollectiongenerator" with the" \
		79		".qhcp project file in $(BUILDDIR)/qthelp, like this:"
		80		@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/libtaskotron.qhcp"
		81		@echo "To view the help file:"
		82		@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/libtaskotron.qhc"
		83
		84		devhelp:
		85		$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
		86		@echo
		87		@echo "Build finished."
		88		@echo "To view the help file:"
		89		@echo "# mkdir -p $$HOME/.local/share/devhelp/libtaskotron"
		90		@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/libtaskotron"
		91		@echo "# devhelp"
		92
		93		epub:
		94		$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
		95		@echo
		96		@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
		97
		98		latex:
		99		$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
		100		@echo
		101		@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
		102		@echo "Run \`make' in that directory to run these through (pdf)latex" \
		103		"(use \`make latexpdf' here to do that automatically)."
		104
		105		latexpdf:
		106		$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
		107		@echo "Running LaTeX files through pdflatex..."
		108		$(MAKE) -C $(BUILDDIR)/latex all-pdf
		109		@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
		110
		111		text:
		112		$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
		113		@echo
		114		@echo "Build finished. The text files are in $(BUILDDIR)/text."
		115
		116		man:
		117		$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
		118		@echo
		119		@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
		120
		121		texinfo:
		122		$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
		123		@echo
		124		@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
		125		@echo "Run \`make' in that directory to run these through makeinfo" \
		126		"(use \`make info' here to do that automatically)."
		127
		128		info:
		129		$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
		130		@echo "Running Texinfo files through makeinfo..."
		131		make -C $(BUILDDIR)/texinfo info
		132		@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
		133
		134		gettext:
		135		$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
		136		@echo
		137		@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
		138
		139		changes:
		140		$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
		141		@echo
		142		@echo "The overview file is in $(BUILDDIR)/changes."
		143
		144		linkcheck:
		145		$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
		146		@echo
		147		@echo "Link check complete; look for any errors in the above output " \
		148		"or in $(BUILDDIR)/linkcheck/output.txt."
		149
		150		doctest:
		151		$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
		152		@echo "Testing of doctests in the sources finished, look at the " \
		153		"results in $(BUILDDIR)/doctest/output.txt."

View Options

docs/source/conf.py

This file was added.

		1		# -- coding: utf-8 --
		2		#
		3		# libtaskotron documentation build configuration file, created by
		4		# sphinx-quickstart on Thu Feb 6 13:52:28 2014.
		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.autodoc']
		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'libtaskotron'
		44		copyright = u'2014, Fedora QA Devel'
		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.0.7'
		52		# The full version, including alpha/beta/rc tags.
		53		release = '0.0.7'
		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
		90		# -- Options for HTML output ---------------------------------------------------
		91
		92		# The theme to use for HTML and HTML Help pages. See the documentation for
		93		# a list of builtin themes.
		94		html_theme = 'nature'
		95
		96		# Theme options are theme-specific and customize the look and feel of a theme
		97		# further. For a list of options available for each theme, see the
		98		# documentation.
		99		#html_theme_options = {}
		100
		101		# Add any paths that contain custom themes here, relative to this directory.
		102		#html_theme_path = []
		103
		104		# The name for this set of Sphinx documents. If None, it defaults to
		105		# "<project> v<release> documentation".
		106		#html_title = None
		107
		108		# A shorter title for the navigation bar. Default is the same as html_title.
		109		#html_short_title = None
		110
		111		# The name of an image file (relative to this directory) to place at the top
		112		# of the sidebar.
		113		#html_logo = None
		114
		115		# The name of an image file (within the static path) to use as favicon of the
		116		# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
		117		# pixels large.
		118		#html_favicon = None
		119
		120		# Add any paths that contain custom static files (such as style sheets) here,
		121		# relative to this directory. They are copied after the builtin static files,
		122		# so a file named "default.css" will overwrite the builtin "default.css".
		123		html_static_path = ['_static']
		124
		125		# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
		126		# using the given strftime format.
		127		#html_last_updated_fmt = '%b %d, %Y'
		128
		129		# If true, SmartyPants will be used to convert quotes and dashes to
		130		# typographically correct entities.
		131		#html_use_smartypants = True
		132
		133		# Custom sidebar templates, maps document names to template names.
		134		#html_sidebars = {}
		135
		136		# Additional templates that should be rendered to pages, maps page names to
		137		# template names.
		138		#html_additional_pages = {}
		139
		140		# If false, no module index is generated.
		141		#html_domain_indices = True
		142
		143		# If false, no index is generated.
		144		#html_use_index = True
		145
		146		# If true, the index is split into individual pages for each letter.
		147		#html_split_index = False
		148
		149		# If true, links to the reST sources are added to the pages.
		150		#html_show_sourcelink = True
		151
		152		# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
		153		#html_show_sphinx = True
		154
		155		# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
		156		#html_show_copyright = True
		157
		158		# If true, an OpenSearch description file will be output, and all pages will
		159		# contain a <link> tag referring to it. The value of this option must be the
		160		# base URL from which the finished HTML is served.
		161		#html_use_opensearch = ''
		162
		163		# This is the file name suffix for HTML files (e.g. ".xhtml").
		164		#html_file_suffix = None
		165
		166		# Output file base name for HTML help builder.
		167		htmlhelp_basename = 'libtaskotrondoc'
		168
		169
		170		# -- Options for LaTeX output --------------------------------------------------
		171
		172		latex_elements = {
		173		# The paper size ('letterpaper' or 'a4paper').
		174		#'papersize': 'letterpaper',
		175
		176		# The font size ('10pt', '11pt' or '12pt').
		177		#'pointsize': '10pt',
		178
		179		# Additional stuff for the LaTeX preamble.
		180		#'preamble': '',
		181		}
		182
		183		# Grouping the document tree into LaTeX files. List of tuples
		184		# (source start file, target name, title, author, documentclass [howto/manual]).
		185		latex_documents = [
		186		('index', 'libtaskotron.tex', u'libtaskotron Documentation',
		187		u'Fedora QA Devel', 'manual'),
		188		]
		189
		190		# The name of an image file (relative to this directory) to place at the top of
		191		# the title page.
		192		#latex_logo = None
		193
		194		# For "manual" documents, if this is true, then toplevel headings are parts,
		195		# not chapters.
		196		#latex_use_parts = False
		197
		198		# If true, show page references after internal links.
		199		#latex_show_pagerefs = False
		200
		201		# If true, show URL addresses after external links.
		202		#latex_show_urls = False
		203
		204		# Documents to append as an appendix to all manuals.
		205		#latex_appendices = []
		206
		207		# If false, no module index is generated.
		208		#latex_domain_indices = True
		209
		210
		211		# -- Options for manual page output --------------------------------------------
		212
		213		# One entry per manual page. List of tuples
		214		# (source start file, name, description, authors, manual section).
		215		man_pages = [
		216		('index', 'libtaskotron', u'libtaskotron Documentation',
		217		[u'Fedora QA Devel'], 1)
		218		]
		219
		220		# If true, show URL addresses after external links.
		221		#man_show_urls = False
		222
		223
		224		# -- Options for Texinfo output ------------------------------------------------
		225
		226		# Grouping the document tree into Texinfo files. List of tuples
		227		# (source start file, target name, title, author,
		228		# dir menu entry, description, category)
		229		texinfo_documents = [
		230		('index', 'libtaskotron', u'libtaskotron Documentation',
		231		u'Fedora QA Devel', 'libtaskotron', 'One line description of project.',
		232		'Miscellaneous'),
		233		]
		234
		235		# Documents to append as an appendix to all manuals.
		236		#texinfo_appendices = []
		237
		238		# If false, no module index is generated.
		239		#texinfo_domain_indices = True
		240
		241		# How to display URL addresses: 'footnote', 'no', or 'inline'.
		242		#texinfo_show_urls = 'footnote'

View Options

docs/source/devguide.rst

This file was added.

1		===========================
2		Taskotron Development Guide
3		===========================
4
5		So, you're interested in getting helping out with libtaskotron? Great, this will
6		help get you started on that.
7
8
9		General Information
10		===================
11
12		Libtaskotron is written mostly in `Python <https://www.python.org/>`_.
13
14		Source Code
15		-----------
16
17		The source code for libtaskotron is in a git repository on bitbucket:
18		https://bitbucket.org/fedoraqa/libtaskotron
19
20		If you submit patches, please use the process of :ref:`submitting-code`.
21
22		Bugs, Issues and Tasks
23		----------------------
24
25		We use `Phabricator <http://phabricator.org/>`_ to track issues and facilitate
26		code reviews for several projects related to libtaskotron and Fedora QA.
27
28		Our phabricator instance can be found at https://phab.qadevel.cloud.fedoraproject.org/
29
30
31		.. _running-tests:
32
33		Running unit and functional tests
34		---------------------------------
35
36		We place a high value on having decent test coverage for the libtaskotron code.
37		In general, tests are written using `pytest <http://pytest.org/>` and are broken
38		up into two types:
39
40		* Unit Tests test the core logic of code. They do not touch the filesystem
41		or interact with any network resources. The unit tests should run very quickly
42
43		* Functional Tests are a set of more comprehensive tests which are allowed
44		to touch the filesystem and/or interact with networked resources. Functional
45		tests are often much slower than unit tests but they offer coverage which is
46		not present in the unit tests.
	kparalUnsubmitted Not Done are not run as often That almost sounds like we run it only very occasionally. I think everyone should run the full functional test suite before pushing a patch. Can we rephrase it a bit? E.g. "They are often slower, but offer better test coverage."
47
48		To run the unit tests::
49
50		py.test testing/
	mkrizekUnsubmitted Not Done The binary is called py.test, at least on my system.
51
52		To run the functional and unit tests::
53
54		py.test -F testing/
	mkrizekUnsubmitted Not Done Same as above.
55
56		Support tools
57		-------------
58
59		There are several tools that, while not required, make the process of developing
60		for libtaskotron significantly easier.
61
62
63		.. _installing-arcanist:
64
65		Arcanist
66		^^^^^^^^
67
68		`Arcanist <https://secure.phabricator.com/book/phabricator/article/arcanist/>`_
69		is a command line interface to Phabricator which can be used to submit code
70		reviews, download/apply code under review among other useful functions.
71
72		As Arcanist is an interface to Phabricator, we strongly recommend that you
73		install it using our packages instead of from the upstream git repos (as
74		described in upstream documentation). That way, there is no question that the
75		Arcanist version used locally is compatible with our Phabricator instance.
76
77		To add our yum repository containing Phabricator related packages, run::
78
79		sudo curl http://repos.fedorapeople.org/repos/tflink/phabricator/fedora-phabricator.repo -o /etc/yum.repos.d/fedora-phabricator.repo
	kparalUnsubmitted Not Done Output redirection doesn't work with `sudo`. Use this instead: sudo curl http://repos.fedorapeople.org/repos/tflink/phabricator/fedora-phabricator.repo -o /etc/yum.repos.d/fedora-phabricator.repo Maybe `fedora-qa-phabricator.repo` would a better file name?
80
81		Once the repository has been configured, install Arcanist using::
82
83		sudo yum install arcanist
84
85		Arcanist is written in PHP and installing it will pull in several PHP packages
86		as dependencies.
87
88
89		.. _installing-gitflow:
90
91		gitflow
92		^^^^^^^
93
94		The `gitflow plugin for git <https://github.com/nvie/gitflow>`_ is another
95		useful, but not required tool that is available in the Fedora repositories.
96
97		To install the gitflow plugin, run::
98
99		sudo yum install gitflow
100
101
102		.. _submitting-code:
103
104		Submitting code
105		---------------
106
107		Libtaskotron follows the `gitflow <http://nvie.com/posts/a-successful-git-branching-model/>`_
108		branching model and with the exception of hotfixes, all changes made should be
109		against the `develop` branch.
110
111		While not required, using the `gitflow plugin for git <https://github.com/nvie/gitflow>`_
112		is recommended as it makes the process significantly easier. See
113		:ref:`installing-gitflow` for instructions on installing gitflow on Fedora.
114
115
116		Start a new feature
117		^^^^^^^^^^^^^^^^^^^
118
119		To start work on a new feature, use::
120
121		git flow feature start TXXX-short-description
122
123		Where `TXXX` is the issue number in Phabricator and `short-description` is a
124		short, human understandable description of the change contained in this branch.
125
126		In general, short reviews are better than long reviews. If you can, please break
127		up features into chunks that are smaller and easier to manage.
128
129
130		Submitting code for review
131		^^^^^^^^^^^^^^^^^^^^^^^^^^
132
133		.. note::
134
135		Make sure to run all unit and functional tests before submitting code for
136		review. Any code that causes test failure will receive requests to fix the
137		offending code or will be rejected. See :ref:`running-tests` for information
138		on running unit and functional tests.
139
140		Code reviews are done through Phabricator, not pull requests. While it is possible
141		to submit code for review through the web interface, :ref:`installing-arcanist`
142		is recommended.
143
144		You do not need to push code anywhere public before submitting a review. Unless
145		there is a good reason to do so (and there are very few), pushing a feature
146		branch to origin is frowned on as it makes repository maintenance more difficult
147		for no real benefit.
148
149		To submit code for review, make sure that your code has been updated with respect
150		to `origin/develop` and run the following from your checked-out feature branch::
151
152		arc diff develop
	kparalUnsubmitted Not Done I have seen `arc` behaving very weirdly very often. Please recommend this command instead: arc diff develop Otherwise it sometimes ends up detecting wrong parent branches, creating new reviews instead of updating existing one, etc.
153
154		The first time that you use Arcanist, it will ask for an API key which can be
155		retrieved from a link contained in that prompt.
156
157		Arcanist will create a new code review on our Phabricator instance and prompt
158		you for information about the testing which has been done, a description of the
159		code under review and people to whom the review should be assigned. If you're
160		not clear on who should review your code, leave the `reviewers` section blank
161		and someone will either review your code or assign the review task to someone
162		who will.
163
164
165		Updating code reviews
166		^^^^^^^^^^^^^^^^^^^^^
167
168		There will often be requests for changes to the code submitted for review. Once
169		the requested changes have been made in your feature branch, commit them and
170		make sure that your branch is still up to date with respect to `origin/develop`.
171
172		To update the existing review, use::
173
174		arc diff develop --update DXXX
	kparalUnsubmitted Not Done When using `arc diff develop`, I have never seen a problem in existing Differential Review detection. But `--update` obviously works as well. For problems mentioned above, I think `develop` should always be a part of the command: arc diff develop or arc diff develop --update DXXX
175
176		Where `DXXX` is the Differential ID assigned to your review when it was
177		originally created.
178
179
180		Pushing code
181		^^^^^^^^^^^^
182
183		Once the review has been accepted, the code needs to be merged into `develop`
184		and pushed to `origin`.
185
186
187		Make sure that your local `develop` branch is up-to-date with `origin/develop`
	kparalUnsubmitted Not Done The problem with `arc land` is that it puts a lot of clutter into your commit message without your control and pushes immediately (you can use special cmdline options to avoid that). I think it's much better to use traditional: git checkout develop git merge --squash feature/TXXX git commit # remove all the clutter from the commit message, just keep in short summary and Differential link git push origin Alternatively, `git flow feature finish` can be used and then `git commit --amend` to remove the clutter.
188		before starting the merge process, else messy commits and merges may ensue.
189		Once `develop` is up-to-date, the basic workflow to use is::
190
191		git checkout feature/TXXX-some-feature
192		git merge --ff-only develop ## sometimes a non-ff merge is needed but should be avoided, if possible
	kparalUnsubmitted Not Done I think that a squash merge is better, because who would like to see a number of "WIP" commits in the log? It makes operations on the history (e.g. navigating or bisecting) much harder. But that's just my personal preference.
	tflinkAuthorUnsubmitted Not Done For that particular line, a squash merge is a really bad idea. That's just updating the feature branch from `develop`. For the actual merge into develop (with the `git flow feature finish`), I could go both ways. Personally, I think that the bigger problem is all the meaningless "WIP" commit messages but that being said, I usually rebase my feature branches before merging them in. Is using `--squash` trustworthy? I usually prefer to to my rebases by hand to make sure that it looks right before merging.
	kparalUnsubmitted Not Done Oh, I misunderstood the line, sorry. In this case, `git merge develop` or `git rebase develop` makes sense, but the `--ff-only` never works, I believe. I tried locally on a trivial example and it didn't work.
	tflinkAuthorUnsubmitted Not Done I guess the question becomes whether to suggest `merge` or `rebase`, then. I think that `rebase` could lead to cleaner history but `merge` would work in more situations. Any objections to suggesting `rebase` and say something like "if you run into problems, please ask for help"?
	kparalUnsubmitted Not Done I have the same understanding as you do. No objections at all.
193		git flow feature finish TXXX-some-feature
	kparalUnsubmitted Not Done Let's recommend this: If you want to push several commits (there are several no-nonsense logically separated commits): If the commits are not yet to your liking, run git rebase -i develop and adjust the commits. Then run git flow feature finish TXXX-some-feature If your feature can be nicely expressed in just a single commit, run: git flow feature finish --squash TXXX-some-feature (This should be identical approach to manually rebasing and squashing commits.)
	tflinkAuthorUnsubmitted Not Done if we go that route, I'd prefer to specify a preferred default. Any objections to saying "a single commit per feature is preferred in most cases."?
	kparalUnsubmitted Not Done I completely agree. Most features are small changes and it's easiest to have them in a single commit.
194		git push origin develop
	kparalUnsubmitted Not Done Any suggestions for what to use as a suggested template? Before pushing, it's nice of you to make the commit message pretty. You can amend the latest commit message: git commit --amend and remove any unnecessary noise (Test Plan, Reviewers, CC, too detailed description) and wrap lines properly. Please keep the review hyperlink.
	tflinkAuthorUnsubmitted Not Done Is that specific enough or should we have an example template?
	kparalUnsubmitted Not Done Isn't that overkill? Just a quick look to `git log` will tell the person how the commit messages usually look like. We can also just say this ("Have a look at how commits usually look like") instead of enumerating things that can possibly be removed.
195
196
197		Reviewing Code
198		--------------
199
200		To review code, use `Phabricator's web interface <https://phab.qadevel.cloud.fedoraproject.org/>`_
201		to submit comments, request changes or accept reviews.
202
203		If you want to look at the code under review locally to run tests or test
204		suggestions prior to posting them, use Arcanist to apply the review code.
205
	kparalUnsubmitted Not Done `arcpatch-DXXX`
206		Make sure that your local repo is at the same base revision as the code under
207		review (usually origin/develop) and run the following command::
208
209		arc patch DXXX
210
211		Where `DXXX` is the review id that you're interested in. Arcanist will grab the
212		code under review and apply it to a local branch named `arcpatch-DXXX`. You can
213		then look at the code locally or make modifications.
214
215		Writing directives
216		==================
217
218		TODO Write documentation on writing directives for libtaskotron
219
220		Documentation
221		=============
222
223		The documentation for libtaskotron is made up of several sources which are
224		combined together into a single document using `Sphinx <http://sphinx-doc.org/>`_.
225
226		Most of the libtaskotron docs are written in `reStructuredText
227		<http://docutils.sourceforge.net/rst.html>`_ (reST) and unless otherwise
228		mentioned, follow the `Python documentation style guide
229		<https://docs.python.org/devguide/documenting.html#style-guide>`_
230
231
232		Building documentation
233		----------------------
234
235		The documentation is easy to build once deps are installed::
	kparalUnsubmitted Not Done Would it make sense to copy this section to `readme.rst` in top-level directory?
236
237		yum install python-sphinx
238
239		To actually build the documentation::
240
241		cd docs/
242		make html
243
244
245		Docstrings
246		----------
247
248		Docstrings should be formatted using a reST-like format which Sphinx's autodoc
249		extension can easily render into HTML.
250
251		Sphinx has several built-in info fields which should be used to document
252		function/method arguments and return data.
253
254
255		The following is an excerpt from `the Sphinx documentation
256		<http://sphinx-doc.org/domains.html#info-field-lists>`_
257
258
259		Inside Python object description directives, reST field lists with these fields
260		are recognized and formatted nicely:
261
262		* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
263		Description of a parameter.
264		* ``type``: Type of a parameter.
265		* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
266		exception is raised.
267		* ``var``, ``ivar``, ``cvar``: Description of a variable.
268		* ``returns``, ``return``: Description of the return value.
269		* ``rtype``: Return type.
270
271		The field names must consist of one of these keywords and an argument (except
272		for ``returns`` and ``rtype``, which do not need an argument). This is best
273		explained by an example::
274
275		.. py:function:: send_message(sender, recipient, message_body, [priority=1])
276
277		Send a message to a recipient
278
279		:param str sender: The person sending the message
280		:param str recipient: The recipient of the message
281		:param str message_body: The body of the message
282		:param priority: The priority of the message, can be a number 1-5
283		:type priority: integer or None
284		:return: the message id
285		:rtype: int
286		:raises ValueError: if the message_body exceeds 160 characters
287		:raises TypeError: if the message_body is not a basestring
288
289		This will render like this:
290
291		.. py:function:: send_message(sender, recipient, message_body, [priority=1])
292		:noindex:
293
294		Send a message to a recipient
295
296		:param str sender: The person sending the message
297		:param str recipient: The recipient of the message
298		:param str message_body: The body of the message
299		:param priority: The priority of the message, can be a number 1-5
300		:type priority: integer or None
301		:return: the message id
302		:rtype: int
303		:raises ValueError: if the message_body exceeds 160 characters
304		:raises TypeError: if the message_body is not a basestring
305
306		It is also possible to combine parameter type and description, if the type is a
307		single word, like this::
308
309		:param int priority: The priority of the message, can be a number 1-5
310
311
312		Directive Documentation
313		-----------------------
314
315		To be determined - likely a variation on the docstring convention
316
317
318		reST Documentation
319		------------------
320
321		The majority of libtaskotron's documentation is in the form of reST files which
322		live in the `docs/source` directory in the git repository.
323
324		For more information see:
325
326		* `reStructuredText Primer <http://sphinx-doc.org/rest.html#rst-primer>`_
327		* `Sphinx Markup Constructs <http://sphinx-doc.org/markup/index.html#sphinxmarkup>`_
328
329
330		ReST Headings
331		^^^^^^^^^^^^^
332		We use the suggested reST headers as outlined in the `Python documentation style
333		guide on section headers <https://docs.python.org/devguide/documenting.html#sections>`_
334		which are:
335
336		.. in case the text isn't clear, the following excerpt was taken directly from
337		the Python documentation style guide at the link directly above this comment
338
339		Section headers are created by underlining (and optionally overlining) the
340		section title with a punctuation character, at least as long as the text::
341
342		=================
343		This is a heading
344		=================
345
346		Normally, there are no heading levels assigned to certain characters as the
347		structure is determined from the succession of headings. However, for the
348		Python documentation, here is a suggested convention:
349
350		* ``#`` with overline, for parts
351		* ``*`` with overline, for chapters
352		* ``=``, for sections
353		* ``-``, for subsections
354		* ``^``, for subsubsections
355		* ``"``, for paragraphs

View Options

docs/source/index.rst

This file was added.

		1		==========================
		2		Libtaskotron Documentation
		3		==========================
		4
		5		What is libtaskotron?
		6		=====================
		7
		8		Libtaskotron is one of the core components which make up the `taskotron`_
		9		system. Libtaskotron is responsible for running tasks written in the
		10		:ref:`taskyaml_section`.
		11
		12		While libtaskotron was designed for use with `Fedora <http://fedoraproject.org>`_,
		13		the Fedora specific parts are isolated and the core should be usable with any
		14		recent Linux distribution.
		15
		16		Libtaskotron and Taskotron should be considered Alpha software. They are
		17		currently under very heavy development and will likely change until we stabilize
		18		the interfaces.
		19
		20		Support
		21		=======
		22		Please direct questions and comments to either the `Fedora QA Devel List
		23		<https://admin.fedoraproject.org/mailman/listinfo/qa-devel>`_ or the `#fedora-qa`
		24		IRC channel on `Freenode <http://freenode.net/>`_.
		25
		26
		27
		28		.. _taskotron: https://fedoraproject.org/wiki/Taskotron
		29
		30		Contents
		31		========
		32
		33		.. toctree::
		34		:maxdepth: 1
		35
		36		devguide
		37		writing_tasks
		38		library
		39
		40
		41		Indices and tables
		42		==================
		43
		44		* :ref:`genindex`
		45		* :ref:`modindex`
		46		* :ref:`search`
		47

View Options

docs/source/library.rst

This file was added.

		1		=====================
		2		libtaskotron API docs
		3		=====================
		4
		5		This isn't final API documentation, more of an example of how we can do API docs.
		6
		7		Once more of our code is using sphinx-style docs, we can start finalizing the
		8		format for this page.
		9
		10		Note that the docs here are for libtaskotron library functions and don't
		11		include directives or task yaml details.
		12
		13
		14		runner (one function with sphinx-style docstrings)
		15		==================================================
		16
		17		.. automodule:: libtaskotron.runner
		18		:members:
		19
		20		check (no sphinx-style docstrings)
		21		==================================
		22
		23		.. automodule:: libtaskotron.check
		24		:members:
		25

View Options

readme.rst

1	libtaskotron proof-of-concept 0.0.1	1		libtaskotron
2	===================================	2		============
3		3
4	This is a proof-of-concept for libtaskotron. The purpose of this is to illustrate	4		This is a proof-of-concept for libtaskotron. The purpose of this is to illustrate
5	where we're going with taskotron and get input on any perceived problems early on	5		where we're going with taskotron and get input on any perceived problems early on
6	before anything is final.	6		before anything is final.
7		7
8	Please keep in mind that this is proof-of-concept code - there are a lot of things	8		Please keep in mind that this is proof-of-concept code - there are a lot of things
9	which are hard-coded and nothing is final. Please don't develop against this code	9		which are hard-coded and nothing is final. Please don't develop against this code
10	unless you've talked to us first.	10		unless you've talked to us first.
▲ Show 20 Lines • Show All 114 Lines • ▼ Show 20 Line(s)		124	You can also see a test coverage of the code, just run::
125		125
126	py.test --functional --cov-report term-missing --cov libtaskotron testing/	126		py.test --functional --cov-report term-missing --cov libtaskotron testing/
127		127
128	A nice HTML-based representation is available if you use `--cov-report html`	128		A nice HTML-based representation is available if you use `--cov-report html`
129	parameter instead.	129		parameter instead.
130		130
131	If you write new tests, be sure to run this to see whether the code is	131		If you write new tests, be sure to run this to see whether the code is
132	sufficiently covered by your tests.	132		sufficiently covered by your tests.
		133
		134		Building Documentation
		135		----------------------
		136
		137		Libtaskotron's documentation is written in `reStructuredText
		138		<http://docutils.sourceforge.net/rst.html>`_ and built using `Sphinx
		139		<http://sphinx-doc.org/>`_.
		140
		141		The documentation is easy to build once deps are installed::
		142
		143		yum install python-sphinx
		144
		145		To actually build the documentation::
		146
		147		cd docs/
		148		make html
		149

Adding initial skeleton for sphinx documentation project. Fixes T139ClosedPublicActions

Details

Diff Detail

Revision Contents

Diff 197

.gitignore

docs/Makefile

docs/source/conf.py

docs/source/devguide.rst

docs/source/index.rst

docs/source/library.rst

readme.rst

Adding initial skeleton for sphinx documentation project. Fixes T139
ClosedPublic
Actions