1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
7 # http://www.apache.org/licenses/LICENSE-2.0
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 # See the License for the specific language governing permissions and
13 # limitations under the License.
15 # Generator of static API documentation for the Nit language
17 # Generate API documentation in HTML format from Nit source code.
22 redef class ToolContext
24 # Nitdoc generation phase
25 var docphase
: Phase = new Nitdoc(self, null)
27 # Directory where the Nitdoc is rendered
28 var opt_dir
= new OptionString("Output directory", "-d", "--dir")
30 # Do not generate documentation for attributes
31 var opt_no_attributes
= new OptionBool("Ignore the attributes", "--no-attributes")
33 # Do not generate documentation for private properties
34 var opt_private
= new OptionBool("Also generate private API", "--private")
36 # Use a shareurl instead of copy shared files
38 # This is usefull if you don't want to store the Nitdoc templates with your
40 var opt_shareurl
= new OptionString("Use shareurl instead of copy shared files", "--shareurl")
42 # Use a custom title for the homepage
43 var opt_custom_title
= new OptionString("Custom title for homepage", "--custom-title")
45 # Display a custom brand or logo in the documentation top menu
46 var opt_custom_brand
= new OptionString("Custom link to external site", "--custom-brand")
48 # Display a custom introduction text before the packages overview
49 var opt_custom_intro
= new OptionString("Custom intro text for homepage", "--custom-overview-text")
51 # Display a custom footer on each documentation page
53 # Generally used to display the documentation or product version.
54 var opt_custom_footer
= new OptionString("Custom footer text", "--custom-footer-text")
58 # If you want to monitor your visitors.
59 var opt_piwik_tracker
= new OptionString("Piwik tracker URL (ex: `nitlanguage.org/piwik/`)", "--piwik-tracker")
61 # Piwik tracker site id
62 var opt_piwik_site_id
= new OptionString("Piwik site ID", "--piwik-site-id")
64 # Do not generate dot/graphviz diagrams
65 var opt_nodot
= new OptionBool("Do not generate graphs with graphviz", "--no-dot")
67 # Do not include highlighted code
68 var opt_nocode
= new OptionBool("Do not generate code with nitlight", "--no-code")
70 # File pattern used to link documentation to source code.
71 var opt_source
= new OptionString("Format to link source code (%f for filename, " +
72 "%l for first line, %L for last line) only works with option --no-code", "--source")
74 # Disable HTML rendering
75 var opt_norender
= new OptionBool("DO not render any HTML", "--no-render")
79 # Display test data and remove the progress bar
80 var opt_test
= new OptionBool("Output test data", "--test")
84 option_context
.add_option
(
85 opt_dir
, opt_no_attributes
, opt_private
,
86 opt_share_dir
, opt_shareurl
, opt_custom_title
,
87 opt_custom_footer
, opt_custom_intro
, opt_custom_brand
,
88 opt_piwik_tracker
, opt_piwik_site_id
,
89 opt_nodot
, opt_nocode
, opt_source
, opt_norender
, opt_test
)
95 # Generate a documentation page
96 fun gen_page
(page
: DocPage, output_dir
: String) do
97 page
.apply_structure
(self)
98 page
.render
(self).write_to_file
("{output_dir}/{page.html_url}")
102 # Nitdoc phase explores the model and generate pages for each mentity found
106 redef fun process_mainmodule
(mainmodule
, mmodules
)
108 var modelbuilder
= toolcontext
.modelbuilder
109 var model
= modelbuilder
.model
111 var min_visibility
= private_visibility
112 if not toolcontext
.opt_private
.value
then min_visibility
= protected_visibility
113 var accept_attribute
= true
114 if toolcontext
.opt_no_attributes
.value
then accept_attribute
= false
116 var catalog
= new Catalog(toolcontext
.modelbuilder
)
117 catalog
.build_catalog
(mainmodule
.model
.mpackages
)
119 var filter
= new ModelFilter(
121 accept_attribute
= accept_attribute
,
122 accept_fictive
= true,
123 accept_generated
= true,
126 accept_extern
= true,
127 accept_empty_doc
= true,
128 accept_example
= true,
129 accept_broken
= false)
131 var doc
= new DocModel(model
, mainmodule
, modelbuilder
, catalog
, filter
)
133 model
.nitdoc_md_processor
= doc
.md_processor
134 doc
.no_dot
= toolcontext
.opt_nodot
.value
135 doc
.no_code
= toolcontext
.opt_nocode
.value
136 doc
.code_url
= toolcontext
.opt_source
.value
137 doc
.share_url
= toolcontext
.opt_shareurl
.value
138 doc
.custom_brand
= toolcontext
.opt_custom_brand
.value
139 doc
.custom_title
= toolcontext
.opt_custom_title
.value
140 doc
.custom_footer
= toolcontext
.opt_custom_footer
.value
141 doc
.custom_intro
= toolcontext
.opt_custom_intro
.value
142 doc
.tracker_url
= toolcontext
.opt_piwik_tracker
.value
143 doc
.piwik_site_id
= toolcontext
.opt_piwik_site_id
.value
146 var test_mode
= toolcontext
.opt_test
.value
147 var no_render
= toolcontext
.opt_norender
.value
148 var output_dir
= toolcontext
.opt_dir
.value
or else "doc"
150 if not no_render
then
154 var share_dir
= toolcontext
.opt_share_dir
.value
or else "{toolcontext.share_dir}/nitdoc"
155 sys
.system
("cp -r -- {share_dir.escape_to_sh}/* {output_dir.escape_to_sh}/")
158 # Collect model to document
159 var mpackages
= model
.collect_mpackages
(filter
)
160 var mgroups
= model
.collect_mgroups
(filter
)
161 var nmodules
= model
.collect_mmodules
(filter
)
162 var mclasses
= model
.collect_mclasses
(filter
)
163 var mprops
= model
.collect_mproperties
(filter
)
165 var mentities
= new Array[MEntity]
166 mentities
.add_all mpackages
167 mentities
.add_all mgroups
168 mentities
.add_all nmodules
169 mentities
.add_all mclasses
170 mentities
.add_all mprops
172 var persons
= doc
.catalog
.persons
173 var tags
= doc
.catalog
.tag2proj
.keys
175 # Prepare progress bar
177 var pages
= 1 # count homepage
178 pages
+= mentities
.length
179 pages
+= persons
.length
182 print
"Generating documentation pages..."
183 var progress
= new TermProgress(pages
, 0)
184 if not test_mode
then progress
.display
188 if not test_mode
then progress
.update
(count
, "homepage")
189 if not no_render
then doc
.gen_page
(new PageHome("Overview"), output_dir
)
191 for mentity
in mentities
do
193 if not test_mode
then progress
.update
(count
, "page {count}/{pages}")
194 if not no_render
then doc
.gen_page
(new PageMEntity(mentity
), output_dir
)
196 for name
, person
in persons
do
198 if not test_mode
then progress
.update
(count
, "page {count}/{pages}")
199 if not no_render
then doc
.gen_page
(new PagePerson(person
), output_dir
)
203 if not test_mode
then progress
.update
(count
, "page {count}/{pages}")
204 if not no_render
then doc
.gen_page
(new PageTag(tag
), output_dir
)
207 if not test_mode
then print
"" # finalise progress
208 if not no_render
then
209 doc
.create_index_file
("{output_dir}/quicksearch-list.js")
210 print
"Documentation produced in `{output_dir}`"
214 print
"Generated {count}/{pages} pages"
216 print
" PageMPackage: {mpackages.length}"
217 print
" PageMGroup: {mgroups.length}"
218 print
" PageMModule: {nmodules.length}"
219 print
" PageMClass: {mclasses.length}"
220 print
" PageMProperty: {mprops.length}"
221 print
" PagePerson: {persons.length}"
222 print
" PageTag: {tags.length}"
229 # Build the catalog from `mpackages`
230 fun build_catalog
(mpackages
: Array[MPackage]) do
232 for p
in mpackages
do
235 modelbuilder
.scan_group
(g
)
238 for gg
in p
.mgroups
do for m
in gg
.mmodules
do
239 for im
in m
.in_importation
.direct_greaters
do
241 if ip
== null or ip
== p
then continue
247 for mpackage
in mpackages
do
248 package_page
(mpackage
)
250 mpackage_stats
(mpackage
)
256 var toolcontext
= new ToolContext
257 var tpl
= new Template
258 tpl
.add
"Usage: nitdoc [OPTION]... <file.nit>...\n"
259 tpl
.add
"Generates HTML pages of API documentation from Nit source files."
260 toolcontext
.tooldescription
= tpl
.write_to_string
263 toolcontext
.process_options
(args
)
264 var arguments
= toolcontext
.option_context
.rest
267 var model
= new Model
268 var mbuilder
= new ModelBuilder(model
, toolcontext
)
269 var mmodules
= mbuilder
.parse_full
(arguments
)
272 if mmodules
.is_empty
then return
273 print
"Parsing code..."
275 toolcontext
.run_global_phases
(mmodules
)