# It is a placeholder to share data between each phase.
class DocModel
- # `DocPage` composing the documentation.
+ # `DocPage` composing the documentation associated to their ids.
#
# This is where `DocPhase` store and access pages to produce documentation.
- var pages = new Array[DocPage]
+ #
+ # See `add_page`.
+ var pages: Map[String, DocPage] = new HashMap[String, DocPage]
# Nit `Model` from which we extract the documentation.
var model: Model is writable
# The entry point of the `model`.
var mainmodule: MModule is writable
+
+ # Add a `page` to this documentation.
+ fun add_page(page: DocPage) do
+ if pages.has_key(page.id) then
+ print "Warning: multiple page with the same id `{page.id}`"
+ end
+ pages[page.id] = page
+ end
end
# A documentation page abstraction.
# the page.
class DocPage
+ # Page uniq id.
+ #
+ # The `id` is used as name for the generated file corresponding to the page
+ # (if any).
+ # Because multiple pages can be generated in the same directory it should be
+ # uniq.
+ #
+ # The `id` can also be used to establish links between pages (HTML links,
+ # HTML anchors, vim links, etc.).
+ var id: String is writable
+
# Title of this page.
var title: String is writable
end
redef class MEntity
+ # ID used as a unique ID and in file names.
+ #
+ # **Must** match the following (POSIX ERE) regular expression:
+ #
+ # ~~~POSIX ERE
+ # ^[A-Za-z_][A-Za-z0-9._-]*$
+ # ~~~
+ #
+ # That way, the ID is always a valid URI component and a valid XML name.
+ fun nitdoc_id: String do return full_name.to_cmangle
+
# Name displayed in console for debug and tests.
fun nitdoc_name: String do return name.html_escape
end
+redef class MModule
+
+ # Avoid id conflict with group
+ redef fun nitdoc_id do
+ if mgroup == null then return super
+ return "{mgroup.full_name}::{full_name}".to_cmangle
+ end
+end
+
redef class MClassDef
redef fun nitdoc_name do return mclass.nitdoc_name
end
# Populates the given DocModel.
redef fun apply do
- for page in doc.pages do page.build_concerns(doc)
+ for page in doc.pages.values do page.build_concerns(doc)
end
end
module doc_console
import semantize
+import doc_extract
import doc::console_templates
# Nitx handles console I/O.
# Pretty prints the results for the console.
fun make_results(nitx: Nitx, results: Array[NitxMatch]): DocPage do
- var page = new DocPage("Results")
+ var page = new DocPage("results", "Results")
page.root.add_child(new QueryResultArticle(self, results))
return page
end
redef fun perform(nitx, doc) do
var name = args.first
var res = new Array[NitxMatch]
- for mentity in doc.search_mentities(name) do
+ for mentity in doc.mentities_by_name(name) do
res.add new MEntityMatch(self, mentity)
end
return res
if len == 1 then
var res = results.first.as(MEntityMatch)
var mentity = res.mentity
- var page = new DocPage("Results")
+ var page = new DocPage("resultats", "Results")
var article = new DefinitionArticle(mentity)
article.cs_title = mentity.name
article.cs_subtitle = mentity.cs_declaration
redef fun perform(nitx, doc) do
var res = new Array[NitxMatch]
var name = args.first
- for page in doc.pages do
+ for page in doc.pages.values do
if name == "*" then # FIXME dev only
res.add new PageMatch(self, page)
else if page.title == name then
return res
end
# else, lookup the model by name
- for mentity in doc.search_mentities(name) do
+ for mentity in doc.mentities_by_name(name) do
if mentity isa MClass then continue
if mentity isa MProperty then continue
res.add new CodeMatch(self, mentity.cs_location, mentity.cs_source_code)
end
redef fun make_results(nitx, results) do
- var page = new DocPage("Code Results")
+ var page = new DocPage("results", "Code Results")
for res in results do
page.add new CodeQueryArticle(self, res.as(CodeMatch))
end
## exploration
-redef class DocModel
-
- # Lists all MEntities in the model.
- private var mentities: Collection[MEntity] is lazy do
- var res = new HashSet[MEntity]
- res.add_all mprojects
- res.add_all mgroups
- res.add_all mmodules
- res.add_all mclasses
- res.add_all mclassdefs
- res.add_all mproperties
- res.add_all mpropdefs
- return res
- end
-
- # Search MEntities that match `name` by their name or namespace.
- private fun search_mentities(name: String): Array[MEntity] do
- var res = new Array[MEntity]
- for mentity in mentities do
- if mentity.name != name and mentity.cs_namespace != name then continue
- res.add mentity
- end
- return res
- end
-end
-
# Visitor looking for initialized `MType` (new T).
#
# See `NewQuery`.
end
end
end
+
+ # Lists all MEntities in the model.
+ #
+ # FIXME invalidate cache if `self` is modified.
+ var mentities: Collection[MEntity] is lazy do
+ var res = new HashSet[MEntity]
+ res.add_all mprojects
+ res.add_all mgroups
+ res.add_all mmodules
+ res.add_all mclasses
+ res.add_all mclassdefs
+ res.add_all mproperties
+ res.add_all mpropdefs
+ return res
+ end
+
+ # Searches MEntities that match `name`.
+ fun mentities_by_name(name: String): Array[MEntity] do
+ var res = new Array[MEntity]
+ for mentity in mentities do
+ if mentity.name != name then continue
+ res.add mentity
+ end
+ return res
+ end
+
+ # Looks up a MEntity by its `namespace`.
+ #
+ # Usefull when `mentities_by_name` by return conflicts.
+ #
+ # Path can be the shortest possible to disambiguise like `Class::property`.
+ # In case of larger conflicts, a more complex namespace can be given like
+ # `project::module::Class::prop`.
+ fun mentities_by_namespace(namespace: String): Array[MEntity] do
+ var res = new Array[MEntity]
+ for mentity in mentities do
+ mentity.mentities_by_namespace(namespace, res)
+ end
+ return res
+ end
+end
+
+redef class MEntity
+ # Looks up a MEntity by its `namespace` from `self`.
+ private fun mentities_by_namespace(namespace: String, res: Array[MEntity]) do end
+
+ private fun lookup_in(mentities: Collection[MEntity], namespace: String, res: Array[MEntity]) do
+ var parts = namespace.split_once_on("::")
+ var name = parts.shift
+ for mentity in mentities do
+ if mentity.name != name then continue
+ if parts.is_empty then
+ res.add mentity
+ else
+ mentity.mentities_by_namespace(parts.first, res)
+ end
+ end
+ end
+end
+
+redef class MProject
+ redef fun mentities_by_namespace(namespace, res) do lookup_in(mgroups, namespace, res)
+end
+
+redef class MGroup
+ redef fun mentities_by_namespace(namespace, res) do lookup_in(mmodules, namespace, res)
+end
+
+redef class MModule
+ redef fun mentities_by_namespace(namespace, res) do lookup_in(mclassdefs, namespace, res)
+end
+
+redef class MClassDef
+ redef fun mentities_by_namespace(namespace, res) do lookup_in(mpropdefs, namespace, res)
end
redef fun apply do
if ctx.opt_nodot.value then return
- for page in doc.pages do
+ for page in doc.pages.values do
var article = page.build_graph(self, doc)
if article == null then continue
# FIXME avoid diff
var name_sorter = new MEntityNameSorter
redef fun apply do
- for page in doc.pages do
+ for page in doc.pages.values do
if page isa MEntityPage then page.build_inh_list(self, doc)
end
end
redef fun apply do
init_output_dir
- for page in doc.pages do
+ for page in doc.pages.values do
page.render(self, doc).write_to_file("{ctx.output_dir.to_s}/{page.html_url}")
end
end
# all properties below are roughly copied from `doc_pages`
# Build page title string
- fun init_title(v: RenderHTMLPhase, doc: DocModel) is abstract
+ fun init_title(v: RenderHTMLPhase, doc: DocModel) do end
# Build top menu template if any.
fun init_topmenu(v: RenderHTMLPhase, doc: DocModel) do
super DocPhase
redef fun apply do
- for page in doc.pages do
+ for page in doc.pages.values do
if not page isa MEntityPage then continue
page.root.build_intro_redef_list(self, doc, page)
end
private var lin_sorter = new MEntityNameSorter
redef fun apply do
- for page in doc.pages do page.apply_linearization(self, doc)
+ for page in doc.pages.values do page.apply_linearization(self, doc)
end
end
# Instanciates documentation pages for the given DocModel.
redef fun apply do
- doc.pages.add new OverviewPage("Overview")
- doc.pages.add new SearchPage("Index")
+ doc.add_page new OverviewPage("overview", "Overview")
+ doc.add_page new SearchPage("search", "Index")
for mgroup in doc.mgroups do
- doc.pages.add new MGroupPage(mgroup.nitdoc_name, mgroup)
+ doc.add_page new MGroupPage(mgroup)
end
for mmodule in doc.mmodules do
- doc.pages.add new MModulePage(mmodule.nitdoc_name, mmodule)
+ doc.add_page new MModulePage(mmodule)
end
for mclass in doc.mclasses do
- doc.pages.add new MClassPage(mclass.nitdoc_name, mclass)
+ doc.add_page new MClassPage(mclass)
end
for mproperty in doc.mproperties do
- doc.pages.add new MPropertyPage(mproperty.nitdoc_name, mproperty)
+ doc.add_page new MPropertyPage(mproperty)
end
end
end
# A DocPage documenting a MEntity.
class MEntityPage
+ autoinit mentity
super DocPage
# Type of MEntity documented by this page.
# MEntity documented by this page.
var mentity: MENTITY
+
+ redef var id is lazy do return mentity.nitdoc_id
+ redef var title is lazy do return mentity.nitdoc_name
end
# A documentation page about a MGroup.
# Populates the given DocModel.
redef fun apply do
- for page in doc.pages do
+ for page in doc.pages.values do
if page isa MEntityPage then page.build_poset(self, doc)
end
end
# Populates the given DocModel.
redef fun apply do
- for page in doc.pages do page.apply_structure(self, doc)
+ for page in doc.pages.values do page.apply_structure(self, doc)
end
end
import ordered_tree
redef class MEntity
- # ID used as a HTML unique ID and in file names.
- #
- # **Must** match the following (POSIX ERE) regular expression:
- #
- # ~~~POSIX ERE
- # ^[A-Za-z_][A-Za-z0-9._-]*$
- # ~~~
- #
- # That way, the ID is always a valid URI component and a valid XML name.
- fun nitdoc_id: String is abstract
-
# URL of this entity’s Nitdoc page.
fun nitdoc_url: String is abstract