Browse Source

Doxygen documentation update

- add some files extensions to doxyfile (*.am *.in *.ac *.patch)
- add a documentation page on autotools usage
Yann Weber 7 years ago
parent
commit
0019c8ee38
2 changed files with 142 additions and 1 deletions
  1. 6
    1
      Doxyfile
  2. 136
    0
      lodel/__init__.py

+ 6
- 1
Doxyfile View File

@@ -824,7 +824,12 @@ FILE_PATTERNS          = *.c \
824 824
                          *.ucf \
825 825
                          *.qsf \
826 826
                          *.as \
827
-                         *.js
827
+                         *.js \
828
+			 *.m4 \
829
+			 *.patch \
830
+			 *.ac \
831
+			 *.am \
832
+			 *.in
828 833
 
829 834
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
830 835
 # be searched for input files as well.

+ 136
- 0
lodel/__init__.py View File

@@ -54,3 +54,139 @@ dyncode = None
54 54
 #
55 55
 #
56 56
 
57
+##@defgroup lodel2_deployment Diffusion and deployment
58
+
59
+##@page lodel2_autotools Lodel2 and autotools integration
60
+#@ingroup lodel2_deployment
61
+#
62
+#Autotools provide a way to distribute a software on Posix platforms.
63
+#
64
+#@section lodel2_autotools_howto Howto use them
65
+#
66
+#Basically you have to run :
67
+#- <code>./bootstrap.sh</code> to generate the configure script( run 
68
+#approximatly <code>aclocal; autoconf; automake</code> or 
69
+#<code>autoreconf</code> )
70
+#- <code>./configure</code> to generate Makefile s
71
+#- <code>make</code> to build lodel2 (actually to generate lodel/buildconf.py
72
+#from @ref lodel/buildconf.py.in )
73
+#
74
+#Here is a list of most usefull targets provided by lodel2's Makefile :
75
+#- automake targets
76
+# - **all** compile the sources (don't do a lot for a script langage)
77
+# - **clean** delete compiled files (don't do a lot for a script langage)
78
+# - **distclean** enhanced comportment compared to default (delete compiled 
79
+#files and generated binary). Here it deletes everything generated by
80
+#<code>./bootstrap.sh && ./configure && make</code>
81
+# - **install** Install lodel2 (for the moment copy the lodel dir in 
82
+#the good path (configurable when running ./configure ) )
83
+# - **uninstall** Remove installed files
84
+#- lodel2 specific targets 
85
+# - **tests**, **check** and **checks** are aliases for running tests
86
+# - **doc** generate the doxygen documentation
87
+# - **em_test** refresh the example/em_test.pickle file using em_test.py
88
+# - **dyncode** generate a dyncode.py file using lefactory in
89
+#lodel/leapi/dyncode.py
90
+#
91
+#@section lodel2_autotools_why Why using autotools
92
+#
93
+#Python has a lot of packaging and distributing solutions, but none of them
94
+#is as convinent, complete, portable as GNU autotools. For example setup.py 
95
+#with distutils has no uninstall target; pip, wheel, easy-install etc brokes 
96
+#totally your distribution packaging/upgrade system etc.
97
+#
98
+#Autotools are portable, integrated by debian packaging system ( see 
99
+#checkinstall) and can support multi langages.
100
+#
101
+#@section lodel2_autotools_whatfor For doing what
102
+#
103
+#Autotools are here to allow distributing and installing Lodel2 on 
104
+#Posix OS. 
105
+#
106
+#The distribution mechanisms handles dependencies checking (NO AUTO INSTALL
107
+#WITH BINARY BLOBS !!!), compiling .py files to pyc and pyo, and copy all files
108
+#in the good directories (python libs, doc, scripts etc)
109
+#
110
+#@section lodel2_autotools_how How autotools are integrated
111
+#
112
+#What we call autotools is in fact a lot of software. In our case we use only
113
+#both of them : 
114
+#<a href="https://www.gnu.org/software/autoconf/autoconf.html#documentation">
115
+#autoconf</a> and 
116
+#<a href="https://www.gnu.org/software/automake/#documentation">automake</a>
117
+#
118
+#A python file is generated ( lodel/buildconf.py from 
119
+#@ref lodel/buildconf.py.in) containing various informations gathered during
120
+#the build process (for example the presence of pymongo or the precense of
121
+#the dependency needed by webui etc.)
122
+#
123
+#@subsection lodel2_autoconf Autoconf
124
+#
125
+#Autoconf job is to handle configure.ac file and generated the configure
126
+#script.
127
+#
128
+#@par Configure script
129
+#The configure script job is to check all dependencies fetch all
130
+#path etc. And when runned it generates all Makefile from the Makefile.in files
131
+#(see @ref lodel2_automake "below" )
132
+#
133
+#@par Autoconf macros
134
+#We use both macro family :
135
+#- <a href="https://www.gnu.org/software/automake/manual/html_node/Python.html">
136
+#default autoconf python macro</a>
137
+#- <a href="https://www.gnu.org/software/pyconfigure/manual/">
138
+#pyconfigure autoconf macros</a>
139
+#@see lodel2_autotools_problems
140
+#
141
+#@subsection lodel2_automake Automake
142
+#
143
+#Automake job is to transform the Makefile.am files into Makefile.in files.
144
+#It handles all target creation for build, clean, install, uninstall etc.
145
+#
146
+#@section lodel2_autotools_problems Encontered problems
147
+#
148
+#@ref lodel2_autoconf "Autoconf" use macro "written in m4" (not sure if m4
149
+#is the macro langage). We use two macros sources : automake default python 
150
+#support & pyconfigure automake macros.
151
+#
152
+#Those macros are broken with python3 (see 
153
+#<a href="https://bugs.launchpad.net/ubuntu/+source/python3-defaults/+bug/1408092">
154
+#the python3 sysconfig bug with debian OS</a> ). There is patched version of 
155
+#these macro in the m4 directory (and the associated patches : 
156
+#@ref m4/python.m4.patch "for automake python macros patch" and 
157
+#@ref m4/python_pyconfigure.m4.patch "for pyconfigure python macros patch")
158
+
159
+##@file m4/python.m4.patch
160
+#@ingroup lodel2_deployment
161
+#@brief Patch of automake python macro to solve a bug in pythondir retrieval 
162
+#on debian
163
+#@see https://bugs.launchpad.net/ubuntu/+source/python3-defaults/+bug/1408092
164
+
165
+##@file m4/python_pyconfigure.m4.patch
166
+#@ingroup lodel2_deployment
167
+#@brief Patch to solve a bug in pyconfigure ac macros in pythondir retrieval 
168
+#on debian
169
+#@see https://bugs.launchpad.net/ubuntu/+source/python3-defaults/+bug/1408092
170
+
171
+##@file m4/python.m4
172
+#@ingroup lodel2_deployment
173
+#@brief Automake macro for python (patched version)
174
+#@see m4/python.m4.patch
175
+
176
+
177
+##@file m4/python_pyconfigure.m4
178
+#@brief Pyconfigure automake macro (patched version)
179
+#@see m4/python_pyconfigure.m4.patch
180
+
181
+##@file configure.ac
182
+#@brief configure script model for autoconf
183
+#@ingroup lodel2_deployment
184
+
185
+##@file Makefile.am
186
+#@brief Makefile model for autotools
187
+#@ingroup lodel2_deployment
188
+
189
+##@file lodel/Makefile.am
190
+#@brief Makefile model for autotools
191
+#@ingroup lodel2_deployment
192
+

Loading…
Cancel
Save