Commits

Yu-Jie Lin committed d60ab75

fix doc build, add more doc

Comments (0)

Files changed (12)

 BUILD_CMD=./setup.py sdist --formats gztar,zip bdist_wininst --plat-name win32
 
 DOC_FILES = docs/conf.py $(wildcard docs/*.rst)
-BPY_FILES = $(wildcard bpy/*.py) $(wildcard bpy/*/*.py)
+BPY_FILES = b.py $(wildcard bpy/*.py) $(wildcard bpy/*/*.py)
 
 # ============================================================================
 
 
 # ============================================================================
 
-doc: docs/_build/html apidoc
+doc: apidoc docs/_build/html
 
 docs/_build/html: $(DOC_FILES) $(BPY_FILES)
 	make -C docs html
 
 docs/apidoc: $(BPY_FILES)
 	rm -rf docs/apidoc
-	sphinx-apidoc -f -H Reference -o docs/apidoc bpy
+	sphinx-apidoc -f -T -o docs/apidoc bpy
 
 # ============================================================================
 
 
 clean:
 	rm -rf *.pyc build dist __pycache__
+	rm -rf docs/apidoc
 	make -C docs clean
 
 # ============================================================================
 More information
 ----------------
 
-You can read smartypants' documentation_ or visit b.py_ on Bitbucket.
+* Documentation_
+* b.py_ on Bitbucket
+* PyPI_
 
 .. _documentation: http://pythonhosted.org/b.py/
 .. _b.py: http://bitbucket.org/livibetter/b.py
+.. _PyPI: https://pypi.python.org/pypi/b.py
   ``%%Content%%`` with generated HTML.
 
 ``checklink``
-  check links in generated HTML using [lnkckr][].
+  check links in generated HTML using lnkckr_.
 
 ``search``
   search blog
+
+.. _lnkckr: https://pypi.python.org/pypi/lnkckr
 """
 
 from __future__ import print_function

bpy/handlers/__init__.py

     },
   }
 
+.. _id_affix:
+
+``id_affix``
+------------
+
 ``id_affix`` is used to avoid conflict across posts' HTML element ID. It may be
 a prefix or suffix, depending on handler's implementation and markup library's
 support. It has three types of value:
 
 * :mod:`bpy.handlers.rst`
 
+``markup_prefix`` and ``markup_suffix``
+---------------------------------------
+
 ``markup_prefix`` and ``markup_suffix`` can be useful for adding header and
 footer content for posts. Another useful case in reStructuredText is you can
 use it for setting up some directives, for example ``.. sectnum::``, so you can
 ensure all posts have prefixing section number if in use conjunction with
 ``.. contents::``.
 
+``smartypants``
+---------------
+
 If ``smartypants`` is enabled, then all generated HTML from markup processor
 will be processed by smartypants_ library.
 
 .. _smartypants: https://pypi.python.org/pypi/smartypants
 
 
+.. _custom-handler:
+
 Writing a custom handler
 ========================
 

bpy/services/__init__.py

 ========= =====================
 
 
+.. _service-options:
+
 Options
 =======
 
   }
 
 
+.. _custom-service:
+
 Writing a custom service
 ========================
 

bpy/services/blogger.py

 # THE SOFTWARE.
 
 """
-Blogger service recognizes the following options:
+Blogger service recognizes the following options in :ref:`brc.py`:
 
 .. code:: python
 
 
 You can use ``blogs`` command to quickly get the blog ID.
 
-You also need to authorize *b.py* to access your Blogger account. Simply using
-``blogs`` command (see *Commands* section) would get you into the authorization
-process::
 
-  $ b.py blogs
+.. _Authorization:
+
+Authorization
+=============
+
+You need to authorize *b.py* to access your Blogger account. Simply using
+``blogs`` command (see *Commands* section) to start the authorization process:
+
+.. code:: sh
+
+  b.py blogs
+
+Once you follow the prompted steps, there should be a b.dat_ created under the
+current working directory, you should keep it safe.
 
 
 .. _b.dat:
 ``b.dat``
 =========
 
-Once you follow the steps and finish, there should be a ``b.dat`` credential
-file created under the current working directory, you should keep it safe.
+``b.dat`` is a credential file for Blogger service, it's read by *b.py* from
+the current directory.
+
+To create the file, please follow Authorization_.
 """
 
 from __future__ import print_function

bpy/services/wordpress.py

 # THE SOFTWARE.
 
 """
-WordPress service recognizes the following options:
+WordPress service recognizes the following options in :ref:`brc.py`:
 
 .. code:: python
 

docs/configuration.rst

 ``brc.py``
 ==========
 
-``brc.py`` the configuration that :doc:`b.py` reads from current working directory,
-it may look like:
+``brc.py`` is the configuration that :doc:`b.py` reads from the current working
+directory, it may look like:
 
 .. code:: python
 
   service = '<service id>'
   service_options = {
-    # see Services section
+    # see below
   }
 
+  # Normally, you only need settings above.
+  # For customized handlers and services, you can specify:
+
   handlers = {
-    # see Handlers section
+    # see below
   }
 
   services = {
-    # see Services section
+    # see below
   }
+
+A normal ``brc.py`` only needs ``service`` and ``service_options``, but you can
+add customized handlers and services.
+
+.. seealso:: :ref:`Service options <service-options>`
+
+.. seealso:: :ref:`Writing a custom handler <custom-handler>`
+
+.. seealso:: :ref:`Writing a custom service <custom-service>`
 it is also used to store information which is needed to update a post later on,
 such as ``id``.
 
-In reStructuredText (different markup has different style of header), a header
-look like
+Generally, header can be simply formed as the following regardless which markup
+language handler you use::
+
+  !b
+  key1: value1
+  key2: value2
+
+  post content goes here
+
+The handler will automatically reformed the header into *comment* after posting
+or updating, the format of comment depends on the markup language. For example,
+in reStructuredText, a header look like
 
 .. code:: rst
 
      id_affix: foobar
      url: http://example.com/2013/01/title-of-something.html
 
-In normal usage, you may specify ``title`` and ``labels``. ``title`` will
-override the post title, if this is missed, the post title will be the filename
-without the extension.
+Making header into comment, so it wouldn't be rendered out if it's processed by
+tools other than *b.py*.
 
-``service``, ``kind``, ``blog``, ``id``, and ``url`` are automatically added
-after a successful posting. ``url`` doesn't actually mean anything, just for
-you to have a record of the URL of a post.
 
-``service`` is the service is used for processing.
+Keys
+====
 
-``kind`` is the type of the posting, ``post`` or ``page``, default is ``post``
-and currently Blogger service only supports ``post``.
+``service``:
+  used for processing.
 
-``categories`` is the catgories, only WordPress service uses this.
+  It could be added automatically after successfully posting.
 
-``draft`` is the post status, ``true``, ``yes``, or ``1`` for draft post,
-otherwise published post. Only WordPress service supports this.
+  .. seealso:: :doc:`apidoc/bpy.services`
 
-``blog`` and ``id`` are very important, they are used in updating post and they
-should not be edited by you.
+``blog``:
+  used in updating post and should not be edited by the user normally.
 
-``id_affix`` is the affix to HTML element ID, see also the General Options of
-Handlers.
+  It could be added automatically after successfully posting.
+  
+``id``:
+  used in updating post and should not be edited by the user normally.
+
+  It could be added automatically after successfully posting.
+
+``title``:
+  override the post title.
+  
+  If not specified, the post title will be the filename without the extension.
+
+``kind``:
+  type of the posting, ``post`` or ``page``, default is ``post``.
+  
+  Blogger service currently only supports ``post``.
+
+  It could be added automatically after successfully posting.
+
+``labels``:
+  labels or tags, comma-separated list.
+
+``categories``:
+  categories, comma-separated list.
+  
+  Only WordPress service uses this.
+
+``draft``:
+  the post status, ``true``, ``yes``, or ``1`` for draft post, otherwise
+  published post.
+
+  Only WordPress service supports this.
+
+``url``:
+  link of the post.
+
+  It could be added automatically after successfully posting.
+
+``id_affix``:
+  the affix to HTML element ID.
+
+  .. seealso:: :ref:`id_affix` in handler options.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to b.py's documentation!
-================================
+b.py documentation
+==================
 
-Contents:
+.. note::
+
+  This documentation is still in its early stage. If anything is unclear or you
+  have any suggestions or questions, please feel free to create an issue in
+  `issue tracker`_.
+
+  .. _issue tracker: https://bitbucket.org/livibetter/b.py/issues
+
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
    b.py
    configuration
    header
-   apidoc/modules
-   changes
+   Changes <changes>
    copyright
 
+References
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   apidoc/bpy
+
+Links
+-----
+
+* b.py_ on Bitbucket
+* PyPI_
+
+.. _documentation: http://pythonhosted.org/b.py/
+.. _b.py: http://bitbucket.org/livibetter/b.py
+.. _PyPI: https://pypi.python.org/pypi/b.py
+
 
 Indices and tables
 ==================

docs/introduction.rst

 Installation
 ============
 
-::
+*b.py* can be installed via ``pip``::
 
-  $ pip install b.py
+  pip install b.py
 
 Or install to user-site, meaning no root required and install at your home
 directory::
 
-  $ pip install --user b.py
+  pip install --user b.py
 
 To upgrade::
 
-  $ pip install --upgrade b.py
+  pip install --upgrade b.py
 
 To uninstall::
 
-  $ pip uninstall b.py
+  pip uninstall b.py
 
 
+.. _Dependencies:
+
 Dependencies
 ============
 
 +------------------+----------------------------------------------------+--------+
 | **Handlers**                                                                   |
 +------------------+----------------------------------------------------+--------+
-| AsciiDoc         | AsciiDoc_                                          | 2      |
+| AsciiDoc         | AsciiDoc_::                                        | 2      |
+|                  |                                                    |        |
+|                  |   pip install asciidoc                             |        |
 +------------------+----------------------------------------------------+--------+
 | HTML             | None                                               | 2 / 3  |
 +------------------+----------------------------------------------------+--------+
-| Markdown         | Markdown_                                          | 2 / 3  |
+| Markdown         | Markdown_::                                        | 2 / 3  |
+|                  |                                                    |        |
+|                  |   pip install markdown                             |        |
 +------------------+----------------------------------------------------+--------+
-| reStructuredText | reStructuredText_                                  | 2 / 3  |
+| reStructuredText | reStructuredText_::                                | 2 / 3  |
+|                  |                                                    |        |
+|                  |   pip install distutils                            |        |
 +------------------+----------------------------------------------------+--------+
 | Text             | None                                               | 2 / 3  |
 +------------------+----------------------------------------------------+--------+
 | **Others**                                                                     |
 +------------------+----------------------------------------------------+--------+
-| lnkckr           | lnkckr_                                            | 2 / 3  |
+| lnkckr           | lnkckr_::                                          | 2 / 3  |
+|                  |                                                    |        |
+|                  |   pip install lnkckr                               |        |
 +------------------+----------------------------------------------------+--------+
-| smartypants      | smartypants_ >= 1.8.0                              | 2 / 3  |
+| smartypants      | smartypants_ >= 1.8.0::                            | 2 / 3  |
+|                  |                                                    |        |
+|                  |   pip install smartypants                          |        |
 +------------------+----------------------------------------------------+--------+
 | **Tests**                                                                      |
 +------------------+----------------------------------------------------+--------+
-| PEP8             |                                                    | 2 / 3  |
+| PEP8             | pep8_::                                            | 2 / 3  |
+|                  |                                                    |        |
+|                  |   pip install pep8                                 |        |
 +------------------+----------------------------------------------------+--------+
-| Pyflakes         |                                                    | 2 / 3  |
+| Pyflakes         | pyflakes_::                                        | 2 / 3  |
+|                  |                                                    |        |
+|                  |   pip install pyflakes                             |        |
 +------------------+----------------------------------------------------+--------+
-| Pylint           |                                                    | 2 / 3  |
+| Pylint           | pylint_::                                          | 2 / 3  |
+|                  |                                                    |        |
+|                  |   pip install pylint                               |        |
 +------------------+----------------------------------------------------+--------+
-| install\_test    | virtualenv, make                                   | 2 / 3  |
+| install\_test    | * virtualenv_::                                    | 2 / 3  |
+|                  |                                                    |        |
+|                  |     pip install pylint                             |        |
+|                  |                                                    |        |
+|                  | * make                                             |        |
 +------------------+----------------------------------------------------+--------+
 
 __ https://developers.google.com/blogger/docs/3.0/api-lib/python
 .. _smartypants: http://pypi.python.org/pypi/smartypants
 .. _lnkckr: https://bitbucket.org/livibetter/lnkckr
 
+.. _pep8: https://pypi.python.org/pypi/pep8
+.. _pyflakes: https://pypi.python.org/pypi/pyflakes
+.. _pylint: https://pypi.python.org/pypi/pylint
+.. _virtualenv: https://pypi.python.org/pypi/virtualenv
+
 
 Services and Handlers
 =====================

docs/tutorial.rst

 Tutorial
 ========
 
+
+Setting up
+==========
+
 You should have completed the steps in :ref:`Installation` and the service sections,
-that is having the following file(s) reside in the directory for your posts:
+that is having the following file(s) reside in the directory for your posts and
+all :ref:`Dependencies` installed properly.
 
 * :mod:`Blogger service <bpy.services.blogger>`: :ref:`brc.py` and :ref:`b.dat`; or
 * :mod:`WordPress service <bpy.services.wordpress>`: :ref:`brc.py`
 
-Let's create a first post, ``my-first-post.rst``:
+
+Creating the first post
+=======================
+
+Let's create a first post, ``my-first-post.rst`` or ``my-first-post.md``, whatever markup language floats your boat:
+
+.. code:: rst
+
+  !b
+  service: blogger
+  title: My First Post
+  labels: blogging
+
+  Hooray, posting frm commandline!
+
+The first three lines are called :doc:`header`, when *b.py* sees ``!b`` in the
+beginning of file, it knows what to do with the header. If you are using
+WordPress, change service line to::
+
+  service: wordpress
+
+
+Posting to the service
+======================
+
+After saves the file, run the following command to post it to the service:
+
+.. code:: sh
+
+  b.py post my-first-post.rst
+
+If it runs without any problems, then open the file again, the header part
+should have been edited by *b.py* and may look like:
 
 .. code:: rst
 
   .. !b
-     title: My First Post
-     labels: blogging
-
-  Hooray, posting frm commandline!
-
-Then issue the command to post it to the service::
-
-  $ b.py post my-first-post.rst
-
-If it runs without problem, then open the file again, the header part would
-have been edited and may look like:
-
-.. code:: rst
-
-  .. !b
+     service: blogger
      kind: post
      url: http://[...].blogspot.com/2013/01/my-first-post.html
      labels: blogging
      id: <THE POST ID>
      title: My First Post
 
+*b.py* will insert some data to header and make header into a comment.
+
 .. seealso:: For the detail of header, please see :doc:`header`.
 
-Now, you spot there is a typo ``frm`` and you fix it. To update the post, run
-the same command as posting::
 
-  $ b.py post my-first-post.rst
+Updating the post
+=================
 
-The ``blog`` and ``id`` in the header tells :doc:`b.py` which post to update.
+After posting to the service, you spot there is a typo ``frm`` and you correct
+it. To update the post, run the same command as posting:
+
+.. code:: sh
+
+  b.py post my-first-post.rst
+
+The post should be updated on the service.
+
+If *b.py* sees ``blog`` and ``id`` in header, then it knows that's a post
+already published, so it will update it instead of creating a new post.