提交: 036f41f846820cd57313583f481e2be7e162c23c - DocIdeas (hg)

Commit MetaInfo

• 修訂: 036f41f846820cd57313583f481e2be7e162c23c (tree)
• 時間: 2018-05-12 23:51:07
• 作者: Albert Mietus < albert AT mietus DOT nl >
• Commiter: Albert Mietus < albert AT mietus DOT nl >

Log Message

Added Blog on Sphinx: allDirectives

Change Summary

• add: Blog/Sphinx/AllDirectives.rst
• add: Blog/Sphinx/SphinxDoc-table.inc
• add: Blog/Sphinx/index.rst

差異

diff -r 629ab914039e -r 036f41f84682 Blog/Sphinx/AllDirectives.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Blog/Sphinx/AllDirectives.rst	Sat May 12 16:51:07 2018 +0200
@@ -0,0 +1,23 @@
+=====================
+All Sphinx Directives
+=====================
+.. Copyright (C) ALbert Mietus, 2018
+
+.. post:: 2018/05/12
+   :category: Sphinx
+   :tags: Sphinx directives
+
+   `Sphinx <http:\\Sphinx-doc.org>`_ comes with a huge number of *directives*. Some are inherited from `RST
+   <http://docutils.sourceforge.net/rst.html>`_, others come from the many extensions that are available. But the is no
+   list of all, or the most used directives in Sphinx.
+
+   Until now ...
+
+The most used directives to document Sphinx itself
+==================================================
+
+With a simple iPython-script, I counted all directives in all (`.rst` & `.py`) files of `Sphinx-doc
+<https://github.com/sphinx-doc/sphinx.git>`_ (*the latest version, on May 10, 2018*); 1758 in total. The table below
+shows them all, sorted in most-used-order.  As you can seem many directives are only used once (`0.06%`) or twice ...
+
+.. include:: SphinxDoc-table.inc

diff -r 629ab914039e -r 036f41f84682 Blog/Sphinx/SphinxDoc-table.inc
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Blog/Sphinx/SphinxDoc-table.inc	Sat May 12 16:51:07 2018 +0200
@@ -0,0 +1,41 @@
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|     Directive      |   %    |     Directive      |   %    |     Directive      |   %    |     Directive      |   %    |
++====================+========+====================+========+====================+========+====================+========+
+|  ``versionadded``  | 17.35% |     ``event``      | 1.14%  |  ``moduleauthor``  | 0.28%  |   ``attention``    | 0.11%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|    ``confval``     | 14.39% |  ``autofunction``  | 1.14%  |    ``digraph``     | 0.28%  |     ``object``     | 0.11%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+| ``versionchanged`` | 6.88%  |      ``math``      | 1.14%  | ``autoexception``  | 0.28%  |    ``todolist``    | 0.11%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|   ``automethod``   | 4.89%  |     ``image``      | 1.08%  |   ``important``    | 0.28%  |   ``cmdoption``    | 0.11%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|     ``option``     | 4.32%  |     ``figure``     | 1.08%  |    ``contents``    | 0.23%  | ``tabularcolumns`` | 0.11%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+| ``autoattribute``  | 4.10%  |     ``index``      | 1.08%  |    ``include``     | 0.23%  | ``directivename``  | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|    ``toctree``     | 3.53%  |    ``function``    | 1.02%  |    ``glossary``    | 0.23%  |   ``testsetup``    | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|      ``note``      | 2.90%  |  ``autosummary``   | 1.02%  |   ``sourcecode``   | 0.23%  |     ``graph``      | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|      ``data``      | 2.84%  |    ``seealso``     | 0.91%  |    ``graphviz``    | 0.23%  |    ``sidebar``     | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|   ``autoclass``    | 2.84%  |    ``warning``     | 0.91%  |    ``ifconfig``    | 0.23%  |    ``centered``    | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|     ``module``     | 2.67%  |      ``todo``      | 0.74%  |    ``cssclass``    | 0.17%  |     ``hlist``      | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|     ``class``      | 1.93%  |     ``method``     | 0.74%  |    ``autodata``    | 0.17%  | ``sectionauthor``  | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|   ``attribute``    | 1.93%  |   ``automodule``   | 0.68%  |    ``doctest``     | 0.17%  | ``productionlist`` | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+| ``literalinclude`` | 1.65%  |    ``describe``    | 0.51%  |    ``testcode``    | 0.17%  |    ``caution``     | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|   ``highlight``    | 1.59%  |      ``raw``       | 0.46%  |   ``testoutput``   | 0.17%  |     ``danger``     | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|      ``only``      | 1.59%  |   ``admonition``   | 0.46%  |     ``topic``      | 0.11%  |     ``error``      | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|     ``rubric``     | 1.54%  |    ``program``     | 0.46%  |      ``tip``       | 0.11%  |  ``staticmethod``  | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+|   ``deprecated``   | 1.42%  |     ``table``      | 0.40%  |   ``exception``    | 0.11%  |    ``userdesc``    | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
+| ``currentmodule``  | 1.14%  |      ``hint``      | 0.34%  |     ``envvar``     | 0.11%  |      ``meta``      | 0.06%  |
++--------------------+--------+--------------------+--------+--------------------+--------+--------------------+--------+
\ No newline at end of file

diff -r 629ab914039e -r 036f41f84682 Blog/Sphinx/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Blog/Sphinx/index.rst	Sat May 12 16:51:07 2018 +0200
@@ -0,0 +1,15 @@
+.. _Sphinx-:
+
+Sphinx-doc (& ReStructuredText)
+===============================
+.. Copyright (C) ALbert Mietus, 2018
+
+`Sphinx <http:\\Sphinx-doc.org>`_ and `reStructuredText (RST) <http://docutils.sourceforge.net/rst.html>`_ are
+great. And there is a lot of documentation for it too. But still, I’m missing some. So I will write it myself
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *
+