Skip to content

Re-organize existing documentation into new structure. #318

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 13, 2017
Merged

Re-organize existing documentation into new structure. #318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
sphinx==1.5.6
sphinx_rtd_theme
20 changes: 20 additions & 0 deletions scripts/linkmonitor/ignored.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
- url: plugin_discovery.html#plugin-creation-and-discovery
reason: named link to first header
- url: single_source_version.html#single-sourcing-the-project-version
reason: named link to first header
- url: deployment.html#application-deployment
reason: named link to first header
- url: patching.html
reason: dropped incomplete topic
- url: plugin_discovery.html#plugin-creation-and-discovery
reason: named link to first header
- url: deployment.html#application-deployment
reason: named link to first header
- url: additional.html#additional-topics
reason: named link to first header
- url: quickstart.html#quickstart
reason: named link to first header
- url: additional.html#additional-topics
reason: named link to first header
- url: platforms.html#platform-integtation
reason: named link to first header
160 changes: 136 additions & 24 deletions scripts/linkmonitor/inventory.yaml
View file
Open in desktop

Large diffs are not rendered by default.

27 changes: 25 additions & 2 deletions scripts/linkmonitor/linkmonitor.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
HERE = os.path.abspath(os.path.dirname(__file__))
INVENTORY_FILENAME = os.path.join(HERE, 'inventory.yaml')
REDIRECTS_FILENAME = os.path.join(HERE, 'redirects.yaml')
IGNORED_FILENAME = os.path.join(HERE, 'ignored.yaml')
ROOT = os.path.abspath(os.path.join(HERE, '..', '..'))
HTML_DIR = os.path.join(ROOT, 'build', 'html')
IGNORED_FILES = [
Expand Down Expand Up @@ -50,6 +51,9 @@ def find_all_named_anchors_in_files(files):
links = set()

for filename in files:
if filename in ('search.html',):
continue

links.add(filename)
anchors = find_all_named_anchors(filename)
links.update(anchors)
Expand Down Expand Up @@ -80,7 +84,13 @@ def load_redirects():
return yaml.load(redirects_file)


def expand_redirects(redirects, inventory):
def load_ignored():
with io.open(IGNORED_FILENAME, 'r') as ignored_file:
raw = yaml.load(ignored_file)
return set([entry['url'] for entry in raw])


def expand_redirects(redirects, inventory, ignored):
valid_redirects = set()
missing_redirects = set()

Expand All @@ -99,6 +109,9 @@ def expand_redirects(redirects, inventory):
# destination page. For the example above, new.html needs to have #1
# #2 and #3 as well.
for source_link in source_links:
if source_link in ignored:
continue

dest_link = source_link.replace(from_, redirect['to'])
if dest_link in inventory:
valid_redirects.add(source_link)
Expand Down Expand Up @@ -139,9 +152,11 @@ def check_command(args):
# TODO: Add another file to list currently defined redirects.
inventory = load_inventory()
redirects = load_redirects()
ignored = load_ignored()
links = find_links()

valid_redirects, missing_redirects = expand_redirects(redirects, inventory)
valid_redirects, missing_redirects = expand_redirects(
redirects, inventory, ignored)
if missing_redirects:
print(
'The following redirects are missing deep link anchors in the '
Expand All @@ -152,6 +167,14 @@ def check_command(args):
missing_links = inventory.difference(links)
missing_links -= valid_redirects

ignored_links = set()
for link in missing_links:
for source_url in ignored:
if link.startswith(source_url):
ignored_links.add(link)

missing_links -= ignored_links

if missing_links:
print('Missing the following deep links:')
for link in missing_links:
Expand Down
54 changes: 54 additions & 0 deletions scripts/linkmonitor/redirects.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,57 @@

- from: old.html
to: new.html

- from: additional.html
to: guides/index.html
- from: quickstart.html
to: tutorials/index.html
- from: platforms.html
to: guides/installing-scientific-packages.html
- from: tutorial.html
to: tutorials/index.html

- from: installing.html
to: tutorials/installing-packages.html
- from: deployment.html
to: discussions/deploying-python-applications.html
- from: requirements.html
to: discussions/install-requires-vs-requirements.html
- from: pip_easy_install.html
to: discussions/pip-vs-easy-install.html
- from: wheel_egg.html
to: discussions/wheel-vs-egg.html

- from: plugin_discovery.html
to: guides/creating-and-discovering-plugins.html
- from: self_hosted_repository.html
to: guides/hosting-your-own-index.html
- from: mirrors.html
to: guides/index-mirrors-and-caches.html
- from: science.html
to: guides/installing-scientific-packages.html
- from: install_requirements_linux.html
to: guides/installing-using-linux-tools.html
- from: multi_version_install.html
to: guides/multi-version-installs.html
- from: extensions.html
to: guides/packaging-binary-extensions.html
- from: namespace_packages.html
to: guides/packaging-namespace-packages.html
- from: single_source_version.html
to: guides/single-sourcing-package-version.html
- from: multiple_python_versions.html
to: guides/supporting-multiple-python-versions.html
- from: appveyor.html
to: guides/supporting-windows-using-appveyor.html
- from: current.html
to: guides/tool-recommendations.html

- from: specifications.html
to: specifications/index.html

- from: distributing.html
to: tutorials/distributing-packages.html
- from: installing.html
to: tutorials/installing-packages.html

29 changes: 0 additions & 29 deletions source/additional.rst
View file
Open in desktop

This file was deleted.

6 changes: 3 additions & 3 deletions source/deployment.rst → ...ussions/deploying-python-applications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

======================
Application Deployment
======================
=============================
Deploying Python applications
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about "Deploy Python applications" or "Deploy a Python application" instead? I was a bit aspirational when I wrote the contributing guide, but one of the guidelines I suggested was to move toward an imperative form (or, really, a truncated question form), since it seems to be a bit more searcher friendly.

I'll go ahead and make similar notes elsewhere, though I don't know if I'd count them as blockers.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I general, I really really try to avoid imperative voice for titles in technical documentation, especially because imperative voice is used to tell the reader what to do to accomplish a task within a section. Gerund construction seems to sit better with me for informing what a section will cover. Django notably uses gerund construction. Try imaging that document with imperative voice - it's a bit harder to process.

(I'm gonna hold off on merging this until you have a chance to respond)

Copy link
Contributor

@ddbeck ddbeck Jun 1, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there's a trend away from the gerund in headings in technical writing, at least for task-oriented documents. The argument for the imperative form is that it's easier for readers to skim for the content that addresses their problem. By using the imperative form, a writer can align more closely with the words that the reader might use to describe their problem, rather than using the words that the writer would use to describe the problem that someone else is having. It's a little bit of trick really; while it's technically the imperative, it's being used a bit more like an infinitive (with the "to" omitted for brevity). There are some other arguments too (like differentiation in ToCs), but this is the big one.

So let's take the deployment heading as an example. Imagine you want to learn about deploying a Python application. You might ask questions like "How do I deploy my Python application?" or "What are the steps to deploy my Python application?" You can pretty readily skim for those formations. The gerund form isn't impossible, but it tends to be a bit less direct (e.g., "How do I go about deploying my Python application?") or doesn't address a task (e.g., "What is deploying a Python application?").

I think it's a good idea to write headings this way (incrementally—we don't need to go and retrofit everything at once) and since you had changed some headings anyway, I figured now was a good time to bring it up. If you're not convinced, then it doesn't need to block the merge—but then we should probably revisit the headings guidance in the contributing guide.

(Oh about that Django doc: I don't love it in either case. There's a lot going on with the ORM abstraction and what it even means to make queries when the abstraction is obscuring the fact that you are making a query. It's got problems with or without gerund headings.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there's a trend away from the gerund in headings in technical writing, at least for task-oriented documents.

Can you provide some samples? I want to see this trend and how it works in practice. Please don't take this as me not believing you, I'm open to changing my stance here (which is why I haven't merged this yet), it's just that there's so many places I see gerund construction over imperative voice, and that's generally been fairly constant in my career. This could be due to bias, as my company's internal style guide explicitly calls for gerund construction. I'm okay with going against the grain, but I'm going to need slightly more convincing.

think it's a good idea to write headings this way (incrementally—we don't need to go and retrofit everything at once) and since you had changed some headings anyway, I figured now was a good time to bring it up. If you're not convinced, then it doesn't need to block the merge—but then we should probably revisit the headings guidance in the contributing guide.

We should get this right now, as changing the heading breaks deep links (which is why I wrote the linkchecker script).

I definitely want you on board with whatever we do, as I don't want to alienate a contributor on a project that frankly needs help. :)

Another suggestion is that we can do a poll on distutils-sig if we can't reach agreement.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you provide some samples?

Sure! I did some contract tech writing at Google recently and saw that their help centers (like Inbox or AdSense) use it often. You see it less often in their developer sites, though there are examples; I particularly like this cool tutorial listing. I've also spotted it in some major sections in the Docker documentation (see the left ToC) recently. I can find more examples, if you like.

it's just that there's so many places I see gerund construction over imperative voice, and that's generally been fairly constant in my career

I'll admit that the imperative form is a little bit trendy and the gerund is way more common. And, honestly, the gerund is not bad. I just think the imperative is a little better.

I definitely want you on board with whatever we do, as I don't want to alienate a contributor on a project that frankly needs help. :)

You're giving the idea a good faith hearing. If you're not convinced, then that's fine. Sincere skepticism or disagreement isn't going to alienate me. Though I'll admit I like getting my way. 😃

Another suggestion is that we can do a poll on distutils-sig if we can't reach agreement.

Nah, that seems a bit much. Just let me know what you think of the examples. If you're not convinced, we can update the guidance and move on.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for all of this. I can definitely see how it could work, but I'm still leaning towards gerund construction.

I'm gonna leave this PR open until Friday and if @ncoghlan or @dstufft want to chime in and let me know their preference I can be swayed, otherwise I'll merge as-is :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no opinion and I am pretty sure I am not qualified to have an opinion.

Copy link
Member

@ncoghlan ncoghlan Jun 8, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think @ddbeck is right that it's a good way to structure a how to guide, but PyPUG is kind of a hybrid of a how to guide and a reference guide at the moment, so I think it makes more sense to defer such a style change until after the restructure.

And especially for the discussions, I think the gerund form more accurately conveys the kind of content to expect - they're more "here are the trade-offs to consider when deciding how to approach this task" rather than the imperative "here is how you should approach this task" (vendors and specific projects can be opinionated on that, while PyPUG avoids choosing sides)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool _ I'm gonna go ahead and merge this then. We can revisit as things evolve - I'm almost convince of a bit of a hybrid - for the tutorials I think I may move to @ddbeck's suggestion.

=============================

:Page Status: Incomplete
:Last Reviewed: 2014-11-11
Expand Down
14 changes: 14 additions & 0 deletions source/discussions/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Discussions
###########

**Discussions** are focused on providing comprehensive information about a
specific topic. If you're just trying to get stuff done, see
:doc:`/guides/index`.

.. toctree::
:maxdepth: 1

deploying-python-applications
pip-vs-easy-install
install-requires-vs-requirements
wheel-vs-egg
0 source/requirements.rst → ...ions/install-requires-vs-requirements.rst
View file
Open in desktop
File renamed without changes.
0 source/pip_easy_install.rst → source/discussions/pip-vs-easy-install.rst
View file
Open in desktop
File renamed without changes.
0 source/wheel_egg.rst → source/discussions/wheel-vs-egg.rst
View file
Open in desktop
File renamed without changes.
0 source/code/appveyor.yml → source/guides/appveyor-sample/appveyor.yml
View file
Open in desktop
File renamed without changes.
0 source/code/build.cmd → source/guides/appveyor-sample/build.cmd
View file
Open in desktop
File renamed without changes.
14 changes: 7 additions & 7 deletions source/plugin_discovery.rst → ...ides/creating-and-discovering-plugins.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
=============================
Plugin creation and discovery
=============================
================================
Creating and discovering plugins
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like before, maybe "Create and discover plugins"?

================================

:Page Status: Complete
:Last Reviewed: 2017-04-10
Expand Down Expand Up @@ -61,8 +61,8 @@ naming convention.
Using namespace packages
========================

:doc:`Namespace packages <namespace_packages>` can be used to provide a
convention for where to place plugins and also provides a way to perform
:doc:`Namespace packages <packaging-namespace-packages>` can be used to provide
a convention for where to place plugins and also provides a way to perform
discovery. For example, if you make the sub-package ``myapp.plugins`` a
namespace package then other :term:`distributions <Distribution Package>` can
provide modules and packages to that namespace. Once installed, you can use
Expand Down Expand Up @@ -117,8 +117,8 @@ to :func:`setup`'s ``packages`` argument instead of using

.. warning:: Namespace packages are a complex feature and there are several
different ways to create them. It's highly recommended to read the
:doc:`namespace_packages` documentation and clearly document which
approach is preferred for plugins to your project.
:doc:`packaging-namespace-packages` documentation and clearly document
which approach is preferred for plugins to your project.

Using package metadata
======================
Expand Down
2 changes: 1 addition & 1 deletion source/self_hosted_repository.rst → source/guides/hosting-your-own-index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _`Hosting your Own Simple Repository`:

==================================
Hosting your Own Simple Repository
Hosting your own simple repository
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like before, maybe "Host your own simple repository"?

==================================

:Page Status: Complete
Expand Down
6 changes: 3 additions & 3 deletions source/mirrors.rst → source/guides/index-mirrors-and-caches.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.. _`PyPI mirrors and caches`:

=======================
PyPI mirrors and caches
=======================
================================
Package index mirrors and caches
================================

:Page Status: Incomplete
:Last Reviewed: 2014-12-24
Expand Down
22 changes: 22 additions & 0 deletions source/guides/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
Guides
######

**Guides** are focused on accomplishing a specific task and assume that you are
already familiar with the basics of Python packaging. If you're looking for an
introduction to packaging, see :doc:`/tutorials/index`.

.. toctree::
:maxdepth: 1

tool-recommendations
installing-using-linux-tools
installing-scientific-packages
multi-version-installs
single-sourcing-package-version
supporting-multiple-python-versions
packaging-binary-extensions
supporting-windows-using-appveyor
packaging-namespace-packages
creating-and-discovering-plugins
index-mirrors-and-caches
hosting-your-own-index
0 source/science.rst → ...guides/installing-scientific-packages.rst
View file
Open in desktop
File renamed without changes.
0 source/install_requirements_linux.rst → ...e/guides/installing-using-linux-tools.rst
View file
Open in desktop
File renamed without changes.
0 source/multi_version_install.rst → source/guides/multi-version-installs.rst
View file
Open in desktop
File renamed without changes.
6 changes: 3 additions & 3 deletions source/extensions.rst → ...ce/guides/packaging-binary-extensions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.. _`Binary Extensions`:

=================
Binary Extensions
=================
===========================
Packaging binary extensions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like before, maybe "Package binary extensions"?

===========================

:Page Status: Incomplete
:Last Reviewed: 2013-12-08
Expand Down
0 source/namespace_packages.rst → ...e/guides/packaging-namespace-packages.rst
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion source/single_source_version.rst → ...uides/single-sourcing-package-version.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _`Single sourcing the version`:

===================================
Single-sourcing the Project Version
Single-sourcing the package version
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like before, maybe "Single source the package version"?

===================================

:Page Status: Complete
Expand Down
0 source/multiple_python_versions.rst → ...s/supporting-multiple-python-versions.rst
View file
Open in desktop
File renamed without changes.
10 changes: 5 additions & 5 deletions source/appveyor.rst → ...des/supporting-windows-using-appveyor.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,11 @@ Visual Studio used includes 64-bit compilers with no additional setup).
appveyor.yml
------------

.. literalinclude:: code/appveyor.yml
.. literalinclude:: appveyor-sample/appveyor.yml
:language: yaml
:linenos:

This file can be downloaded from `here <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/code/appveyor.yml>`__.
This file can be downloaded from `here <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/guides/appveyor-sample/appveyor.yml>`__.

The ``appveyor.yml`` file must be located in the root directory of your
project. It is in ``YAML`` format, and consists of a number of sections.
Expand Down Expand Up @@ -123,7 +123,7 @@ environment to use the SDK compiler for 64-bit builds on Python 3.3 and 3.4.
For projects which do not need a compiler, or which don't support 3.3 or 3.4 on
64-bit Windows, only the ``appveyor.yml`` file is needed.

`build.cmd <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/code/build.cmd>`__
`build.cmd <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/guides/ppveyor-sample/build.cmd>`__
is a Windows batch script that runs a single command in an environment with the
appropriate compiler for the selected Python version. All you need to do is to
set the single environment variable ``DISTUTILS_USE_SDK`` to a value of ``1``
Expand Down Expand Up @@ -228,9 +228,9 @@ Support scripts

For reference, the SDK setup support script is listed here:

``code/build.cmd``
``appveyor-sample/build.cmd``

.. literalinclude:: code/build.cmd
.. literalinclude:: appveyor-sample/build.cmd
:language: bat
:linenos:

Expand Down
2 changes: 1 addition & 1 deletion source/current.rst → source/guides/tool-recommendations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _`Tool Recommendations`:

====================
Tool Recommendations
Tool recommendations
====================

:Page Status: Complete
Expand Down
9 changes: 4 additions & 5 deletions source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,10 @@ This guide is maintained on `github
.. toctree::
:maxdepth: 1

current
installing
distributing
additional
specifications
tutorials/index
guides/index
discussions/index
specifications/index
key_projects
glossary
support
Expand Down
22 changes: 0 additions & 22 deletions source/patching.rst
View file
Open in desktop

This file was deleted.

8 changes: 0 additions & 8 deletions source/platforms.rst
View file
Open in desktop

This file was deleted.

Loading