3577
Comment:
|
3597
|
Deletions are marked like this. | Additions are marked like this. |
Line 24: | Line 24: |
* make docs conform to the python documentation style guide * clean up Sphinx syntax and reStructuredText usage |
* <!> make docs conform to the python documentation style guide (%50) * <!> clean up Sphinx syntax and reStructuredText usage (%50) |
Packaging Sprint 2/3 April 2011
Schedule
Start at 9:00am EST on Saturday and Sunday.
Participants
- Kelsey Hightower(Lead) - Atlanta (online) (2/3)
- Elson Rodriguez - Atlanta (online) (2/3)
- Tarek Ziade - Mountain View (online) (3)
- Guillermo López-Anglada - Frankfurt am Main (online) (3)
- Rafael Villar Burke - Madrid (online) (3)
- Piotr Dobrogost - Milanówek, Poland (online) (3)
You can participate online by joining the #distutils channel on freenode and adding your name above.
Sprint Goals
remove all distutils2 occurrences and replace them with packaging.
fix some spelling and grammar errors
make docs conform to the python documentation style guide (%50)
clean up Sphinx syntax and reStructuredText usage (%50)
fix Sphinx errors and warnings
start to re-work the doc that lives outside the packaging folder, that refers to installing/building stuff
reorganize the doc into sections:
- end-users
- developers
- package managers
Requirements
Clone Tarek's cpython fork from Bitbucket and brush up on reStructuredText and Sphinx.
Hg repository
hg clone https://bitbucket.org/tarek/cpython Most work will take place under the cpython/Doc/packaging/ directory.
Markup and doc generation
Docs are written using reStructuredText markup and auto-generated using Sphinx.
Hosting
Most sprinters will be working remotely, feel free to meetup in small groups and update details here.
Updates
Sprint Report Day 1
Today was pretty productive as we managed to get the docs building without errors or warnings using the cpython method of building the docs.
Major Changes
- removed Doc/packaging/conf.py
- docs will be built using the standard cpython build process, this local sphinx conf.py is no longer required
- removed updated pkgutil.rst doc from Doc/packaging/
- relocate under Doc/library/pkgutil.rst?
- disabled use of the Sphinx autodoc plugin (automodule, autoclass, etc)
- Seems we cannot use the autodoc plugin without some changes to how we build cpython docs. We mainly need sphinx Python 3 support so features like automodule works.
- docs have been split up between 3 directories:
- enduser
- developer
- packager
- changed the labels within Doc/packaging/ to use _packaging as a prefix.
- make it clear we are referencing packaging and not distutils
- label names must be unique in the entire documentation source
.. _metadata becomes .. _packaging-metadata
- added the index directive at the top of all docs under Doc/packaging/packaging/
- prevents duplicate objects, distutils and packaging conflict when generating the index.
.. index:: module: packaging
- prevents duplicate objects, distutils and packaging conflict when generating the index.
- used sed to search and replace occurrences of distutils, distutils2, and Distutils2
- s/Disutils2/Packaging/g
- s/distutils2/packaging/g
- s/distutils/packaging/g
Sprint Report Day 2
Work continues on normalizing how we use Sphinx and reST in the packaging docs.
Major Changes
Who's working on what?
- Kelsey is working on Sphinx related fixes and improvements.
- Guillermo is working on improving the readability of the enduser docs.
- Elson is working on improving the readability of the packager docs.