PageRenderTime 50ms CodeModel.GetById 23ms RepoModel.GetById 0ms app.codeStats 0ms

/ga.en.rst

https://bitbucket.org/lbesson/web-sphinx
ReStructuredText | 86 lines | 56 code | 30 blank | 0 comment | 0 complexity | 5d5b8ea4a653673977e0c975d9064fa4 MD5 | raw file
    

  1. .. meta::
    2. 

  2.    :description lang=en: How to use Google Analytics in a Sphinx project
    3. 

  3.    :description lang=fr: Utiliser Google Analytics dans un projet Sphinx
    4. 

  4. 

  5. #################################################
    6. 

  6.  How to use Google Analytics in a Sphinx project
    7. 

  7. #################################################
    8. 

  8. 

  9. .. warning:: I no longer advise to use Google Analytics, and I have entirely removed it from my webpages, and I will no longer update these tutorials. As they would still be available from Google Cache or Archive.org websites, I prefer to keep this page online.
    10. 

  10. 

  11. .. note:: This short page is focusing on *Google Analytics*
    12. 

  12. 

  13.    For more information, it might be useful to consult first one of these pages:
    14. 

  14.     * `en.wikipedia.org/wiki/Google_Analytics <https://en.wikipedia.org/wiki/Google_Analytics>`_,
    15. 

  15.     * `www.google.com/analytics <https://www.google.com/analytics/>`_.
    16. 

  16. 

  17. 

  18. .. note:: This short page is also focusing on Sphinx
    19. 

  19. 

  20.    Therefore, for more information, it might be useful to have in mind how Sphinx works,
    21. 

  21.    and in particular how to use HTML templating support `sphinx-doc.org/templating.html <http://sphinx-doc.org/templating.html>`_.
    22. 

  22. 

  23. 

  24. « Vanilla » Google Analytics code
    25. 

  25. ---------------------------------
    26. 

  26. The default code to add in every page is the following piece of JavaScript:
    27. 

  27. 

  28. .. code-block:: javascript
    29. 

  29. 

  30.    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    31. 

  31.    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    32. 

  32.    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    33. 

  33.    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    34. 

  34.    ga('create', 'UA-38514290-15', 'ga-beacon.appspot.com');
    35. 

  35.    ga('send', 'pageview');
    36. 

  36. 

  37. 

  38. The first and intuitive solution is, *of course*, to modify the main *template* document
    39. 

  39. (usually, it should be ``_templates/layout.html`` ou ``.templates/layout.html``)
    40. 

  40. and to add it this code, between two tags ``<script type="text/javascript">`` and ``</script>``.
    41. 

  41. 

  42. If possible, you have to add this piece of code at *the end of the page*, to reduce the page's loading time.
    43. 

    44. 

  44. A smaller piece of code
    45. 

  45. -----------------------
    46. 

  46. *(And also easier to maintain !)*
    47. 

  47. You just have to create a small ``ga.js`` script contenaning
    48. 

  48. the previous piece of code, and add it somewhere on your website.
    49. 

  49. 

  50. For instance: `ga.js <http://perso.crans.org/besson/_static/ga.js>`_.
    51. 

  51. 

  52. Then you have to load it in every webpage with one-line of ``HTML`` code
    53. 

  53. at the end of the file (in the ``<bottom>`` paragraph or at the end of ``<body>``) :
    54. 

  54. 

  55. .. code-block:: html
    56. 

  56. 

  57.    <script type="text/javascript" async src="http://perso.crans.org/besson/_static/ga.js"></script>
    58. 

  58. 

  59. 

  60. Moreover, the ``async`` tag will improve the speed of the page, by
    61. 

  61. loading asynchronously the ``ga.js`` script. Awesome!
    62. 

  62. 

  63. How and where adding it
    64. 

  64. -----------------------
    65. 

  65. For example, you can take a look at my `layout.html <https://bitbucket.org/lbesson/web-sphinx/src/master/.templates/layout.html#cl-290>`_.
    66. 

  66. 

  67. ------------------------------------------------------------------------------
    68. 

  68. 

  69. Other solutions ?
    70. 

  70. -----------------
    71. 

  71. Sphinx has an extension for Google Analytics, see `on the list of extensions here <http://sphinx-doc.org/latest/develop.html#extensions>`_ (`this folder of the sphinx-contrib repository <https://bitbucket.org/birkenfeld/sphinx-contrib/src/default/googleanalytics/>`_).
    72. 

  72. It's quick and simple, and working well, and for example I am using it for small Sphinx projects, see for examples: `<infoMP/TPs/solution>`_, `<infoMP/DSs/solution>`_ and `<infoMP/TDs/solution>`_.
    73. 

    74. 

  74. 

  75. .. seealso::
    76. 

  76. 

  77.    GA-Beacon (`<beacon.html>`_)
    78. 

  78.       How to use a *one-pixel* image to use Google Analytics
    79. 

  79.       to measure the audience of a page, or an email.
    80. 

  80. 

  81.    Statistics for Google Analytics (`<stats-google-analytics.en.html>`_)
    82. 

  82.       A small sum-up of the use of Google Analytics on this website (from the last 3 years),
    83. 

  83.       and some plots to illustrate the visits and visitors this website got.
    84. 

  84. 

  85. 

  86. .. (c) Lilian Besson, 2011-2021, https://bitbucket.org/lbesson/web-sphinx/
    87. 

  87.