fgdocx  0.2 [master]
FlightGear API Docs
DoxyMain-fgdocx.cpp
Go to the documentation of this file.
1 /**
2  * @file DoxyMain-fgdocx.cpp
3  *
4  * \mainpage API Index
5  *
6  * - The projects below are regenerated every few hours on a cron.
7  * - IMPORTANT: The docs are generated from latest bleeding edge (next branches) where appropritate.
8  *
9  * \warning The repository source are soon moving from gitorious.org to gitlab.com
10  *
11  * \htmlinclude projects_index.html
12  *
13  * For more info see \ref About
14  *
15  *****************************************************
16  * \page About About the FG Docx Project
17  *
18  * \section intro Introduction
19  * The \a 'tool' of this project is <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a>, a tool to parse source code and then output
20  * into various formats; the one we are interested in is \b html.
21  *
22  * <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a> is a very clever application, you can throw anything at it and it tries
23  * to make sense of code, create some docmentation out of nothing sometimes; see <a href="fgdata">FG Data</a>.
24  *
25  *
26  * \section Goals Goals
27  * - Autocreate the docs from source
28  * - Make it a reliable endpoint for everyone to referance at
29  * - Update the docs regularily
30  * - Current using jenkins, currently thanks FGx project at http://jenkins.fgx.ch
31  * - Create a presentable and useful interface
32  * - Make the documentation interlink, ie linking flightgear, simgear, osg api's together
33  *
34  * \section Contact Contact
35  * Please send bug report, suggestions etc to [pete at freeflightsim dot org]
36  *
37  *
38  *******************************************************************
39  * \page doxy_default doxy-default.conf
40  * - Below are the contents of the doxy-default.conf file
41  *
42  * \include doxy-default.conf
43  *
44  *
45  *******************************************************************
46  * \page config_yaml projects.config.yaml
47  * - The build configuration is contained within the file \b etc/projects.config.yaml
48  * - The configuration is loaded by \ref Config and ProjectConfig
49  *
50  * \section config_directives Config Directives
51  * The format is explained with
52  * the plib example. This is parsed from the yaml file to a python dictionary
53  * \code
54  plib:
55  title: Portable Game Library
56  runlevel: 10
57  color: "#539053"
58  version:
59  number: 1.8.5
60  repo: svn
61  checkout: https://plib.svn.sourceforge.net/svnroot/plib/trunk
62  official: 1
63  copy:
64  - etc/DoxyMain-plib.cpp
65  doxy_args:
66  INPUT: DoxyMain-plib.cpp src/
67  HTML_COLORSTYLE_HUE: 120
68  HTML_COLORSTYLE_SAT: 80
69  HTML_COLORSTYLE_GAMMA: 220
70  * \endcode
71  * - \b plib - is the project key, and output directory. Must be unique.
72  *
73  * \subsection title_config title:
74  * The title of the project, will appear in indexed as titles
75  * \subsection color_config color:
76  * This is the css color used on the index page.
77  * @warning MUST be enclosed in double quotes <code>"#aabbcc"</code>
78  *
79  * \subsection runlevel_config runlevel:
80  * Some project need to be build before others, eg osg and plib before simgear.
81  * When buildall is run, the list is sorted by this order
82  * - \b 0 - Runs first, no dependancies
83  * - \b 100 - Reserved for \b fg-docs This project must be suild last
84  * \subsection version_config Version Config:
85  * The version requires either:
86  * - the \b number: eg <code>number: 1.8.5</code>
87  * - or a \b file: eg <code>file: version.txt</code> in the project directory
88  * - If both are present, \b file: comes after \b number:
89  * - If neither is present <b>-na-</b> is presented
90  * @see ::Project.get_version()
91  *
92  * \subsection repo_config repo:
93  * The kind of repo: either \b git or \b svn
94  *
95  * \subsection checkout_config checkout:
96  * The url for checking out
97  *
98  * \subsection branch_config branch:
99  * The git branch to checkout, defaults to \b master
100  *
101  * \subsection official_config official:
102  * TBA, the idea is to recognise upstream
103  *
104  * \subsection copy_config copy:
105  * A list of file to copy from the ROOT to the project temp dir
106  * - \b doxy_file: The doxy file to use, if there is one, otherwise omit
107  * \subsection doxy_args_conf doxy_args:
108  * A list of doxygen config args. This is appended to the doxy source and overries settings.
109  *
110  * \section tags_config Tags Config
111  * The "tag" project are interlinked,
112  * \code
113  * tag: simgear plib osg
114  * \endcode
115  *
116  * \section current_config Current Config
117  * \include projects.config.yaml
118  *
119  *
120  ****************************************************************************
121  * \page build_process The Build Process
122  *
123  *
124  * \section build_steps How it works
125  * - Checkout the project from https://git.gitorious.org/~ffs/flightgear-docs-project
126  * - Run the script which completed the steps below
127  * \code
128  * build_docs.py buildall
129  * \endcode
130  * -# Reads the \ref Projects config from \ref config_yaml
131  * -# Sorts the projects via \ref runlevel_config. Note that the \b fgdocx project itself is 100 = last
132  * -# Runs \ref ::project.Project.build_project() for each project
133  * - Checks if its either a git or svn repos
134  * - Checks out the repo if is doesnt exist ie new
135  * - Updates the reps with <code>git pull, svn up</code>
136  * - Copies across the required files to build
137  * - Create doxy file by either:
138  * - Read an existing doxy file if in the configuration and found
139  * - Or use the \ref doxy_default (eg no doxy file in project)
140  * The process is to:
141  * - Create the \b temp/ directory for project
142  * - Create the \b build/ directory ie the www_root/
143  * - Checkout a repository (tried git externals with difficulties)
144  *
145  *
146  * \section Requirements
147  * @note It was decided to use python for scripting as this has more libs to automate the process.
148  *
149  * The following is required on the target machine
150  * - \b git
151  * - \b svn
152  * - \b python
153  * - \b python-svn
154  * - \b python-git
155  * - \b python-yaml
156  * - \b python-simplejson
157  * - \ref Doxygen - must be version 1.8+ (currently compiled on a dedicated machine)
158  *
159  *
160  *
161  *
162  */