From: Alexandre Terrasa Date: Mon, 2 Feb 2015 18:36:59 +0000 (+0100) Subject: nitdoc: introduce `doc_base` module X-Git-Tag: v0.7.2~30^2~14 X-Git-Url: http://nitlanguage.org nitdoc: introduce `doc_base` module This module introduces new Nitdoc concepts: * DocModel * DocPage and DocComposite * DocPhase These concepts will be used in further commits to "phasify" Nitdoc. Signed-off-by: Alexandre Terrasa --- diff --git a/src/doc/doc_base.nit b/src/doc/doc_base.nit new file mode 100644 index 0000000..56b57c2 --- /dev/null +++ b/src/doc/doc_base.nit @@ -0,0 +1,219 @@ +# This file is part of NIT ( http://www.nitlanguage.org ). +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Base entities shared by all the nitdoc code. +module doc_base + +import toolcontext +import doc_model # FIXME maintain compatibility with old templates. + +# The model of a Nitdoc documentation. +# +# `DocModel` contains the list of the `DocPage` to be generated. +# +# The model is populated through `DocPhase` to be constructed. +# It is a placeholder to share data between each phase. +class DocModel + + # `DocPage` composing the documentation. + # + # This is where `DocPhase` store and access pages to produce documentation. + var pages = new Array[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 +end + +# A documentation page abstraction. +# +# The page contains a link to the `root` of the `DocComposite` that compose the +# the page. +class DocPage + + # Title of this page. + var title: String is writable + + # Root element of the page. + # + # `DocPhase` access the structure of the page from the `DocRoot`. + var root = new DocRoot + + redef fun to_s do return title +end + +# `DocPage` elements that can be nested in another. +# +# `DocComposite` is an abstraction for everything that go in a `DocPage` like +# sections, articles, images, lists, graphs... +# +# It provides base services for nesting mechanisms following the +# *Composite pattern*. +# The composed structure is a tree from a `DocRoot` that can be manipulated +# recursively. +abstract class DocComposite + + # Parent element. + var parent: nullable DocComposite = null + + # Does `self` have a `parent`? + fun is_root: Bool do return parent == null + + # Children elements contained in `self`. + # + # Children are ordered, this order can be changed by the `DocPhase`. + var children = new Array[DocComposite] + + # Does `self` have `children`? + fun is_empty: Bool do return children.is_empty + + # Add a `child` to `self`. + # + # Shortcut for `children.add`. + fun add(child: DocComposite) do children.add child +end + +# The `DocComposite` element that contains all the other. +# +# The root uses a specific subclass to provide different a different behavior +# than other `DocComposite` elements. +class DocRoot + super DocComposite + + # No op for `RootSection`. + redef fun parent=(p) do end +end + +# Base page elements. + +# `DocSection` are used to break the documentation page into meaningfull parts. +# +# The content of the documentation summary is based on the section structure +# contained in the DocComposite tree. +class DocSection + super DocComposite +end + +# `DocArticle` are pieces of documentation. +# +# They maintains the content (text, list, image...) of a documentation page. +class DocArticle + super DocComposite +end + +# A DocPhase is a step in the production of a Nitdoc documentation. +# +# Phases work from a `DocModel`. +# Specific phases are used to populate, organize, enhance and render the content +# of the documentation pages. +# +# See `doc_phases` for available DocPhase. +class DocPhase + + # Link to the ToolContext to access Nitdoc tool options. + var ctx: ToolContext + + # `DocModel` used by this phase to work. + var doc: DocModel + + # Starting point of a `DocPhase`. + # + # This is where the behavior of the phase is implemented. + # Phases can populate, edit or render the `doc` from here. + fun apply is abstract +end + +redef class ToolContext + + # Directory where the Nitdoc is rendered. + var opt_dir = new OptionString("output directory", "-d", "--dir") + + # Shortcut for `opt_dir.value` with default "doc". + var output_dir: String is lazy do return opt_dir.value or else "doc" + + redef init do + super + option_context.add_option(opt_dir) + end +end + +# Catalog properties by kind. +class PropertiesByKind + # The virtual types. + var virtual_types = new PropertyGroup[MVirtualTypeProp]("Virtual types") + + # The constructors. + var constructors = new PropertyGroup[MMethod]("Contructors") + + # The attributes. + var attributes = new PropertyGroup[MAttribute]("Attributes") + + # The methods. + var methods = new PropertyGroup[MMethod]("Methods") + + # The inner classes. + var inner_classes = new PropertyGroup[MInnerClass]("Inner classes") + + # All the groups. + # + # Sorted in the order they are displayed to the user. + var groups: SequenceRead[PropertyGroup[MProperty]] = [ + virtual_types, + constructors, + attributes, + methods, + inner_classes: PropertyGroup[MProperty]] + + # Add each the specified property to the appropriate list. + init with_elements(properties: Collection[MProperty]) do add_all(properties) + + # Add the specified property to the appropriate list. + fun add(property: MProperty) do + if property isa MMethod then + if property.is_init then + constructors.add property + else + methods.add property + end + else if property isa MVirtualTypeProp then + virtual_types.add property + else if property isa MAttribute then + attributes.add property + else if property isa MInnerClass then + inner_classes.add property + else + abort + end + end + + # Add each the specified property to the appropriate list. + fun add_all(properties: Collection[MProperty]) do + for p in properties do add(p) + end + + # Sort each group with the specified comparator. + fun sort_groups(comparator: Comparator) do + for g in groups do comparator.sort(g) + end +end + +# An ordered list of properties of the same kind. +class PropertyGroup[E: MProperty] + super Array[E] + + # The title of the group, as displayed to the user. + var title: String +end diff --git a/src/doc/doc_pages.nit b/src/doc/doc_pages.nit index 38e6cdf..c4a6ef7 100644 --- a/src/doc/doc_pages.nit +++ b/src/doc/doc_pages.nit @@ -1418,74 +1418,6 @@ class NitdocClass end end -# Groups properties by kind. -private class PropertiesByKind - # The virtual types. - var virtual_types = new PropertyGroup[MVirtualTypeProp]("Virtual types") - - # The constructors. - var constructors = new PropertyGroup[MMethod]("Contructors") - - # The attributes. - var attributes = new PropertyGroup[MAttribute]("Attributes") - - # The methods. - var methods = new PropertyGroup[MMethod]("Methods") - - # The inner classes. - var inner_classes = new PropertyGroup[MInnerClass]("Inner classes") - - # All the groups. - # - # Sorted in the order they are displayed to the user. - var groups: SequenceRead[PropertyGroup[MProperty]] = [ - virtual_types, - constructors, - attributes, - methods, - inner_classes: PropertyGroup[MProperty]] - - # Add each the specified property to the appropriate list. - init with_elements(properties: Collection[MProperty]) do add_all(properties) - - # Add the specified property to the appropriate list. - fun add(property: MProperty) do - if property isa MMethod then - if property.is_init then - constructors.add property - else - methods.add property - end - else if property isa MVirtualTypeProp then - virtual_types.add property - else if property isa MAttribute then - attributes.add property - else if property isa MInnerClass then - inner_classes.add property - else - abort - end - end - - # Add each the specified property to the appropriate list. - fun add_all(properties: Collection[MProperty]) do - for p in properties do add(p) - end - - # Sort each group with the specified comparator. - fun sort_groups(comparator: Comparator) do - for g in groups do comparator.sort(g) - end -end - -# A Group of properties of the same kind. -private class PropertyGroup[E: MProperty] - super Array[E] - - # The title of the group, as displayed to the user. - var title: String -end - # A MProperty page class NitdocProperty super NitdocPage