Skip to content

Clean up documentation #2578

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 11 commits into from
Jan 13, 2017
Merged

Clean up documentation #2578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
42f18b0
Remove core.search_sites
lukegb Jan 5, 2017
64a64b5
Remove import_intersphinx
lukegb Jan 5, 2017
e4c9d7e
Remove sync_builds management command
lukegb Jan 5, 2017
8f48a82
Refer to public API from user documentation
lukegb Jan 5, 2017
f1fa137
Fix i18n section header depth
lukegb Jan 5, 2017
8fba212
Remove reference to ops-docs
lukegb Jan 5, 2017
c0554f0
Correct title underline in user-defined-redirects
lukegb Jan 5, 2017
b0507c0
Remove now-outdated GSoC 2014 page
lukegb Jan 5, 2017
cda95a0
Add some unloved documents to index.rst
lukegb Jan 5, 2017
da8ec4c
Tidy up api/core.rst
lukegb Jan 5, 2017
2b9fd8f
Move builds.models.Version attribute docs next to attributes
lukegb Jan 12, 2017
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
33 changes: 27 additions & 6 deletions docs/api/core.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,6 @@
.. automodule:: readthedocs.core.models
:members:

:mod:`readthedocs.core.search_sites`
------------------------------------
.. automodule:: readthedocs.core.search_sites
:members:

:mod:`readthedocs.core.views`
-----------------------------
.. automodule:: readthedocs.core.views
Expand All @@ -36,9 +31,35 @@
-------------------------------------------
This is where custom ``manage.py`` commands are defined.

.. automodule:: readthedocs.core.management.commands.build_files
.. automodule:: readthedocs.core.management.commands.archive
:members:

.. automodule:: readthedocs.core.management.commands.clean_builds
:members:

.. automodule:: readthedocs.core.management.commands.import_github_language
:members:

.. automodule:: readthedocs.core.management.commands.import_github
:members:

.. automodule:: readthedocs.core.management.commands.pull
:members:

.. automodule:: readthedocs.core.management.commands.reindex_elasticsearch
:members:

.. automodule:: readthedocs.core.management.commands.set_metadata
:members:

.. automodule:: readthedocs.core.management.commands.symlink
:members:

.. automodule:: readthedocs.core.management.commands.update_api
:members:

.. automodule:: readthedocs.core.management.commands.update_repos
:members:

.. automodule:: readthedocs.core.management.commands.update_versions
:members:
65 changes: 0 additions & 65 deletions docs/gsoc.rst
View file
Open in desktop

This file was deleted.

6 changes: 3 additions & 3 deletions docs/i18n.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ Administrative Tasks


Updating Localization Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To update the translation source files (eg if you changed or added translatable
strings in the templates or Python code) you should run ``python manage.py
Expand All @@ -262,7 +262,7 @@ crowd-sourced online translation tool.
.. _i18n-compiling:

Compiling to MO
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^

Gettext doesn't parse any text files, it reads a binary format for faster
performance. To compile the latest PO files in the repository, Django provides
Expand All @@ -281,7 +281,7 @@ make sure you don't forcibly add them to the repository.


Transifex Integration
~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^

To push updated translation source files to Transifex, run ``tx
push -s`` (for English) or ``tx push -t <language>`` (for non-English).
Expand Down
10 changes: 7 additions & 3 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ We pull your code from your Subversion_, Bazaar_, Git_, and Mercurial_ repositor
Then we build documentation and host it for you.
Think of it as *Continuous Documentation*.

The code is open source, and `available on github`_.
The code is open source, and `available on GitHub`_.
Copy link
Member

Choose a reason for hiding this comment

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

This is a link, so the link text should be updated.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Oops, good catch. Thanks.


.. _Read the docs: http://readthedocs.org/
.. _Sphinx: http://sphinx.pocoo.org/
Expand All @@ -18,7 +18,7 @@ The code is open source, and `available on github`_.
.. _Bazaar: http://bazaar.canonical.com/
.. _Git: http://git-scm.com/
.. _Mercurial: http://mercurial.selenic.com/
.. _available on github: http://github.com/rtfd/readthedocs.org
.. _available on GitHub: http://github.com/rtfd/readthedocs.org

The main documentation for the site is organized into a couple sections:

Expand All @@ -30,7 +30,6 @@ Information about development is also available:

* :ref:`dev-docs`
* :ref:`design-docs`
* :ref:`ops-docs`

.. _user-docs:

Expand All @@ -46,6 +45,8 @@ Information about development is also available:
faq
yaml-config
guides/index
api
embed

.. _about-docs:

Expand All @@ -58,6 +59,8 @@ Information about development is also available:
ethical-advertising
sponsors
open-source-philosophy
story
talks

.. _feature-docs:

Expand Down Expand Up @@ -87,6 +90,7 @@ Information about development is also available:
:caption: Developer Documentation

install
api/index
changelog
tests
docs
Expand Down
2 changes: 1 addition & 1 deletion docs/user-defined-redirects.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Note that the ``/`` at the start doesn't count the ``/en/latest``,
but just the user-controlled section of the URL.

Exact Redirects
--------------
---------------

If you're redirecting from an old host AND you aren't maintaining old paths for your
documents, a Prefix Redirect won't suffice and you'll need to create *Exact Redirects*
Expand Down
36 changes: 13 additions & 23 deletions readthedocs/builds/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,40 +32,30 @@


class Version(models.Model):

"""
Attributes
----------

``identifier``
The identifier is the ID for the revision this is version is for. This
might be the revision number (e.g. in SVN), or the commit hash (e.g. in
Git). If the this version is pointing to a branch, then ``identifier``
will contain the branch name.

``verbose_name``
This is the actual name that we got for the commit stored in
``identifier``. This might be the tag or branch name like ``"v1.0.4"``.
However this might also hold special version names like ``"latest"``
and ``"stable"``.

``slug``
The slug is the slugified version of ``verbose_name`` that can be used
in the URL to identify this version in a project. It's also used in the
filesystem to determine how the paths for this version are called. It
must not be used for any other identifying purposes.
"""
project = models.ForeignKey(Project, verbose_name=_('Project'),
related_name='versions')
type = models.CharField(
_('Type'), max_length=20,
choices=VERSION_TYPES, default='unknown',
)
# used by the vcs backend

#: The identifier is the ID for the revision this is version is for. This
#: might be the revision number (e.g. in SVN), or the commit hash (e.g. in
#: Git). If the this version is pointing to a branch, then ``identifier``
#: will contain the branch name.
identifier = models.CharField(_('Identifier'), max_length=255)

#: This is the actual name that we got for the commit stored in
#: ``identifier``. This might be the tag or branch name like ``"v1.0.4"``.
#: However this might also hold special version names like ``"latest"``
#: and ``"stable"``.
verbose_name = models.CharField(_('Verbose Name'), max_length=255)

#: The slug is the slugified version of ``verbose_name`` that can be used
#: in the URL to identify this version in a project. It's also used in the
#: filesystem to determine how the paths for this version are called. It
#: must not be used for any other identifying purposes.
slug = VersionSlugField(_('Slug'), max_length=255,
populate_from='verbose_name')

Expand Down
11 changes: 0 additions & 11 deletions readthedocs/core/management/commands/import_intersphinx.py
View file
Open in desktop

This file was deleted.

55 changes: 0 additions & 55 deletions readthedocs/core/management/commands/sync_builds.py
View file
Open in desktop

This file was deleted.

4 changes: 0 additions & 4 deletions readthedocs/core/search_sites.py
View file
Open in desktop

This file was deleted.