Update more links, add API documentation.

Merged from https://code.launchpad.net/~jelmer/brz/more-doc-improvements/+merge/358955

.bzrignore

@@ -73,3 +73,4 @@ breezy/_*.pyd
 .testrepository
 selftest.log
 .coverage
+doc/developers/api

Makefile

@@ -105,12 +105,6 @@ realclean: clean
 	rm -f breezy/*_pyx.c breezy/bzr/*_pyx.c
 	rm -f breezy/_simple_set_pyx.h breezy/_simple_set_pyx_api.h
 
-# Build API documentation
-docfiles = brz breezy
-api-docs:
-	mkdir -p api/html
-	pydoctor --make-html --docformat='restructuredtext' --html-output=api/html $(docfiles)
-
 # build tags for emacs and vim
 TAGS:
 	ctags -R -e breezy
@@ -159,8 +153,8 @@ docs-sphinx: html-sphinx
 
 # Clean out generated documentation
 clean-sphinx:
-	cd doc/en && make clean
-	cd doc/developers && make clean
+	$(MAKE) -C doc/en clean
+	$(MAKE) -C doc/developers clean
 
 SPHINX_DEPENDENCIES = \
         doc/en/release-notes/index.txt \
@@ -184,32 +178,32 @@ doc/%/make.bat: doc/en/make.bat
 
 # Build the html docs using Sphinx.
 html-sphinx: $(SPHINX_DEPENDENCIES)
-	cd doc/en && make html
-	cd doc/developers && make html
+	$(MAKE) -C doc/en html
+	$(MAKE) -C doc/developers api html
 
 # Build the PDF docs using Sphinx. This requires numerous LaTeX
 # packages. See http://sphinx.pocoo.org/builders.html for details.
 # Note: We don't currently build PDFs for the Russian docs because
 # they require additional packages to be installed (to handle
 # Russian hyphenation rules, etc.)
 pdf-sphinx: $(SPHINX_DEPENDENCIES)
-	cd doc/en && make latex
-	cd doc/developers && make latex
-	cd doc/en/_build/latex && make all-pdf
-	cd doc/developers/_build/latex && make all-pdf
+	$(MAKE) -C doc/en latex
+	$(MAKE) -C doc/developers latex
+	$(MAKE) -C doc/en/_build/latex all-pdf
+	$(MAKE) -C doc/developers/_build/latex all-pdf
 
 # Build the CHM (Windows Help) docs using Sphinx.
 # Note: HtmlHelp Workshop needs to be used on the generated hhp files
 # to generate the final chm files.
 chm-sphinx: $(SPHINX_DEPENDENCIES)
-	cd doc/en && make htmlhelp
-	cd doc/developers && make htmlhelp
+	$(MAKE) -C doc/en htmlhelp
+	$(MAKE) -C doc/developers htmlhelp
 
 
 # Build the texinfo files using Sphinx.
 texinfo-sphinx: $(SPHINX_DEPENDENCIES)
-	cd doc/en && make texinfo
-	cd doc/developers && make texinfo
+	$(MAKE) -C doc/en texinfo
+	$(MAKE) -C doc/developers texinfo
 
 ### Documentation Website ###
 

breezy/bzr/smart/medium.py

@@ -32,12 +32,16 @@
 import sys
 import time
 
+try:
+    import _thread
+except ImportError:
+    import thread as _thread
+
 import breezy
 from ...lazy_import import lazy_import
 lazy_import(globals(), """
 import select
 import socket
-import thread
 import weakref
 
 from breezy import (
@@ -432,7 +436,7 @@ def _write_out(self, bytes):
         tstart = osutils.timer_func()
         osutils.send_all(self.socket, bytes, self._report_activity)
         if 'hpss' in debug.debug_flags:
-            thread_id = thread.get_ident()
+            thread_id = _thread.get_ident()
             trace.mutter('%12s: [%s] %d bytes to the socket in %.3fs'
                          % ('wrote', thread_id, len(bytes),
                             osutils.timer_func() - tstart))

breezy/doc_generate/conf.py

@@ -21,7 +21,13 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.ifconfig', ]
+extensions = [
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx_epytext',
+    # 'sphinxcontrib.napoleon', # TODO: for Google docstrings
+    ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -216,3 +222,7 @@
 
 # Authors of the documents
 brz_team = u'Breezy Developers'
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}

brz

@@ -47,7 +47,8 @@ if os.name == "posix":
     try:
         locale.setlocale(locale.LC_ALL, '')
     except locale.Error as e:
-        sys.stderr.write('brz: warning: %s\n'
+        sys.stderr.write(
+            'brz: warning: %s\n'
             '  bzr could not set the application locale.\n'
             '  Although this should be no problem for bzr itself, it might\n'
             '  cause problems with some plugins. To investigate the issue,\n'
@@ -61,7 +62,8 @@ if os.name == "posix":
 try:
     import breezy
 except ImportError as e:
-    sys.stderr.write("brz: ERROR: "
+    sys.stderr.write(
+        "brz: ERROR: "
         "Couldn't import breezy and dependencies.\n"
         "Please check the directory containing breezy is on your PYTHONPATH.\n"
         "\n")
@@ -73,10 +75,10 @@ if breezy.version_info[:3] != _script_version:
         "This may indicate an installation problem.\n"
         "breezy is version %s from %s\n"
         "brz is version %s from %s\n" % (
-        breezy._format_version_tuple(breezy.version_info),
-        breezy.__path__[0],
-        breezy._format_version_tuple(_script_version),
-        __file__))
+            breezy._format_version_tuple(breezy.version_info),
+            breezy.__path__[0],
+            breezy._format_version_tuple(_script_version),
+            __file__))
 
 
 import breezy.breakin

byov.conf

@@ -9,6 +9,10 @@ subunit.clone = (git clone https://github.com/testing-cabal/subunit.git ../subun
 fastimport.clone = (git clone git://jelmer.uk/python-fastimport.git ../fastimport.git)
 fastimport.install = (cd ../fastimport.git && ./setup.py install --user)
 fastimport.install3 = (cd ../fastimport.git && python3 ./setup.py install --user)
+sphinx_epytext.install = (pip install sphinx_epytext)
+sphinx_epytext.install3 = (pip3 install sphinx_epytext)
+flake8.install = (pip install flake8)
+flake8.install3 = (pip3 install flake8)
 
 [brz]
 # FIXME: we're stuck on xenial
@@ -21,12 +25,12 @@ fastimport.install3 = (cd ../fastimport.git && python3 ./setup.py install --user
 
 # FIXME: Arguably this should be vm.build_deps=brz but it requires either an
 # available package or at least a debian/ dir ? -- vila 2018-02-23
-brz.build_deps = gcc, debhelper, python, python-all-dev, python3-all-dev, python-configobj, python3-configobj, python-docutils, python3-docutils, python-paramiko, python3-paramiko, python-subunit, python3-subunit, python-testtools, python3-testtools, subunit, cython, cython3, python-flake8, python3-flake8
+brz.build_deps = gcc, debhelper, python, python-all-dev, python3-all-dev, python-configobj, python3-configobj, python-docutils, python3-docutils, python-paramiko, python3-paramiko, python-subunit, python3-subunit, python-testtools, python3-testtools, subunit, cython, cython3, python-pip, python3-pip, python-setuptools, python3-setuptools
 subunit.build_deps = python-testscenarios, python3-testscenarios, python-testtools, python3-testtools
 vm.packages = {brz.build_deps}, {subunit.build_deps}, bzr, git, python-junitxml
 [brz-xenial]
 vm.release = xenial
-byoci.setup.command = ({dulwich.clone} && {dulwich.install} && {dulwich.install3} && {fastimport.clone} && {fastimport.install} && {fastimport.install3} && {subunit.clone})
+byoci.setup.command = ({dulwich.clone} && {dulwich.install} && {dulwich.install3} && {fastimport.clone} && {fastimport.install} && {fastimport.install3} && {subunit.clone} && {flake8.install} && {flake8.install3} && {sphinx_epytext.install} && {sphinx_epytext.install3})
 # FIXME: bzr log -l2 should be by default -- vila 2018-03-09
 byoci.tests.command = bash -o pipefail -c "bzr log -l2 && PYTHONPATH=../subunit/python:$PYTHONPATH PATH=../subunit/filters:$PATH make check-ci | subunit2junitxml -o ../results.xml -f | subunit2pyunit"
 [brz-bionic]

doc/developers/HACKING.txt

@@ -12,7 +12,7 @@ the Breezy mailing list.  To propose a correction or addition to this
 document, send a merge request or new text to the mailing list.
 
 The latest developer documentation can be found online at
-http://doc.bazaar.canonical.com/developers/.
+https://www.breezy-vcs.org/developers/.
 
 Getting Started
 ###############
@@ -52,7 +52,7 @@ Planning and Discussing Changes
 
 There is a very active community around Breezy. Mostly we meet on IRC
 (#bzr on irc.freenode.net) and on the mailing list. To join the Breezy
-community, see http://wiki.bazaar.canonical.com/BzrSupport.
+community, see https://www.breezy-vcs.org/pages/support.html.
 
 If you are planning to make a change, it's a very good idea to mention it
 on the IRC channel and/or on the mailing list. There are many advantages
@@ -205,9 +205,7 @@ The key tools we use to enable these practices are:
 
 * Patch Queue Manager - https://launchpad.net/pqm/
 
-For further information, see <http://wiki.bazaar.canonical.com/BzrDevelopment>.
-
-
+For further information, see <https://www.breezy-vcs.org/developers/>.
 
 
 Preparing a Sandbox for Making Changes to Breezy
@@ -294,10 +292,10 @@ doc/en/whats-new/
 
 
 Automatically-generated API reference information is available at
-<http://people.canonical.com/~mwh/bzrlibapi/>.
+<https://www.breezy-vcs.org/developers/api/>.
 
 See also the `Breezy Architectural Overview
-<http://doc.bazaar.canonical.com/developers/overview.html>`_.
+<https://www.breezy-vcs.org/developers/overview.html>`_.
 
 
 Core Topics
@@ -533,7 +531,7 @@ stuff covered above, "core" developers have responsibility for:
 
 * reviewing changes
 * planning releases
-* managing releases (see `Releasing Breezy <http://doc.bazaar.canonical.com/developers/releasing.html>`_)
+* managing releases (see `Releasing Breezy <https://www.breezy-vcs.org/developers/releasing.html>`_)
 
 .. note::
   Removing barriers to community participation is a key reason for adopting

doc/developers/api-readme.txt

@@ -0,0 +1,3 @@
+This is the API documentation for Breezy.
+
+It's still a work in progress.

doc/developers/code-style.txt

@@ -396,7 +396,7 @@ Test coverage
 =============
 
 All code should be exercised by the test suite.  See the `Bazaar Testing
-Guide <http://doc.bazaar.canonical.com/developers/testing.html>`_ for detailed
+Guide <http://www.breezy-vcs.org/developers/testing.html>`_ for detailed
 information about writing tests.
 
 

doc/developers/conf.py

@@ -10,7 +10,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path = [os.path.abspath('../..')] + sys.path
+sys.path = [os.path.abspath('../..'), os.path.abspath('api')] + sys.path
 
 # Most of the configuration for Breezy docs is defined here ...
 from breezy.doc_generate.conf import *

doc/developers/contribution-quickstart.txt

@@ -8,14 +8,9 @@ If you want to fix or improve something in Bazaar, we want to help you.
 You can ask at any time for help, on the list, on irc, or through a merge
 proposal on Launchpad.
 
-In particular, the rostered
-`Patch Pilot <http://wiki.bazaar.canonical.com/PatchPilot>`_ 
-is an experienced developer who will help you get your changes in, through
-code review, advice, debugging, writing tests, or whatever it takes.
-
 * `Bazaar mailing list <http://lists.ubuntu.com/mailman/listinfo/bazaar>`_
 
-* IRC in channel ``#bzr`` on ``irc.ubuntu.com``
+* IRC in channel ``#bzr`` on ``irc.freenode.net``
 
 
 Starting

doc/developers/development-repo.txt

@@ -171,7 +171,7 @@ Reporting problems
 
 If you need any help or encounter any problems, please contact the developers
 via the usual ways, i.e. chat to us on IRC or send a message to our mailing
-list. See http://wiki.bazaar.canonical.com/BzrSupport for contact details.
+list. See https://www.breezy-vcs.org/pages/support.html for contact details.
 
 
 Technical notes

doc/developers/index-plain.txt

@@ -11,7 +11,7 @@ Overall developer documentation
 * `Architectural Overview <overview.html>`_ |--| describes some of the
   most important classes and concepts.
 
-* `bzrlib API reference <http://people.canonical.com/~mwh/bzrlibapi/>`_
+* `breezy API reference <https://www.breezy-vcs.org/developers/api/>`_
   (external link)
   |--| automatically generated API reference information
 
@@ -77,7 +77,7 @@ Plans
 Specifications
 ==============
 
-* `API versioning <api-versioning.html>`_ |--| bzrlib API versioning.
+* `API versioning <api-versioning.html>`_ |--| breezy API versioning.
 
 * `Apport error reporting <apport.html>`_ |--| Capture data to report
   bugs.
@@ -93,7 +93,8 @@ Specifications
 * `Groupcompress <groupcompress-design.html>`_ |--| Notes on the compression
   technology used in CHK repositories.
 
-* `Indices <indices.html>`_ |--| The index facilities available within bzrlib.
+* `Indices <indices.html>`_ |--| The index facilities available within
+  breezy.
 
 * `Inventories <inventory.html>`_ |--| Tree shape abstraction.
 
@@ -108,7 +109,7 @@ Specifications
 * `Repository stream <repository-stream.html>`_ |--| Notes on streaming data
   for repositories (a layer above the container format).
 
-* `Integration Guide <integration.html>`_ |--| A guide to integrate bzrlib into
+* `Integration Guide <integration.html>`_ |--| A guide to integrate breezy into
   any python application.
 
 * `Breezy and case-insensitive file systems <case-insensitive-file-systems.html>`_