Simple tree-like "index" page

[tihomir-kit]

Hi,

First off - awesome tool, thnx!

A question I have is - would it be possible to have some sort of a file which would basically list all the documented stuff in a nested "tree-like" list format? I have something like that in one of my libs.

I think it could be a nice "overview" of the documented code page. I.e. instead of having to drill down from the AssemblyPageName as a starting point, someone could just come to this tree-like page and have an easy overview of what's all the functionality that a library provides . Does that makes sense?

I'm making a bunch of libraries for colleagues I'm working with, and I think if they just land on the AssemblyPageName and have to click around a lot to even find out what the library is about, they might miss a lot of functionality. If that had an easy tree-like overview, it would be basically a lot of basic info at a glance.

Thnx!

[Doraku]

Like a big index? this can definitely be done! I am just not sure where it should be, on the assembly page? on the namespace page if it is unique (as the assembly page will be skipped in this case)? a new index page specifically for this? all of the above with a configuration setting? Without thinking too much into it I would go with option 3, a new <DefaultDocumentationGeneratedPages> value Index. It could look something like this:

• MyNamespace
  • Classes
  • MyClass1
    • Fields
    • field1
    • field2
    • Methods
    • Method1
    • Method2
  • MyClass2
  • Structs
  • MyStruct1

Or maybe like this:

• MyNamespace Namespace
  • MyClass1 Class
  • field1 Field
  • field2 Field
  • Method1 Method
  • Method2 Method
  • MyClass2 Class
  • MyStruct1 Struct

to be a little more compact. What do you think?

[tihomir-kit]

Thanks for the quick reply. I'd say it if was configurable, that would probably be the best option for many people.

Both lists seem fine to me. I guess that's personal preference, what people would want to display. I'd be happy with either of the two.

[hairlesshobo]

+1 on the index idea +1 on making it configurable +1 putting it on its own page

I think an index like this is a great idea. In my own use case, I would likely use it as the input for some shell scripts to modify it then spit out as yaml to use to automatically generate the nav section of my MkDocs project.

Also, tossing this out there... This tool is great. It already has so much more power than every other xmldoc to markup tool I've seen. Thank you for your awesome work and thank you for helping us all out so quickly when we post an idea or issue!

[Doraku]

After this short message I will past what I am currently generating, I am still unsure about the quantity of info that should be here. Not putting the summary seems like there is not enough and putting it feels too heavy, it also completely overlap with the current table display of the next level of members so maybe if you chose to include the index in a page it should replace the tables completely?

Current index

DefaultEcs

This is the full API documentation of DefaultEcs.

• Namespaces
  • DefaultEcs The DefaultEcs namespace contains types to put in place the Entity Component System pattern.
    
  • Classes
    • AoTHelper Provides a set of methods to help the generation of generic code for AoT compilation.
      
    • Methods
      • [RegisterComponent<T>()](AoTHelper_RegisterComponentT().md 'DefaultEcs.AoTHelper.RegisterComponent<T>()') Registers the type [T](AoTHelper_RegisterComponentT().md#DefaultEcs_AoTHelper_RegisterComponentT()_T 'DefaultEcs.AoTHelper.RegisterComponent<T>().T') so it can freely be used in ComponentAttribute.
        
      • [RegisterMessage<T>()](AoTHelper_RegisterMessageT().md 'DefaultEcs.AoTHelper.RegisterMessage<T>()') Registers the type [T](AoTHelper_RegisterMessageT().md#DefaultEcs_AoTHelper_RegisterMessageT()_T 'DefaultEcs.AoTHelper.RegisterMessage<T>().T') so SubscribeAttribute can freely be used on method like the delegate MessageHandler<T>(T) to automatically subscribe when using IPublisherExtension on a World instance.
        
      • [RegisterUnmanagedComponent<T>()](AoTHelper_RegisterUnmanagedComponentT().md 'DefaultEcs.AoTHelper.RegisterUnmanagedComponent<T>()') Registers the unmanaged type [T](AoTHelper_RegisterUnmanagedComponentT().md#DefaultEcs_AoTHelper_RegisterUnmanagedComponentT()_T 'DefaultEcs.AoTHelper.RegisterUnmanagedComponent<T>().T') so it can freely be used in ComponentAttribute and by Set<T>(T).
        
    • ComponentCloner Exposes a way to clone one Entity components to an other.
      
    • Constructors
      • [ComponentCloner()](ComponentCloner_ComponentCloner().md 'DefaultEcs.ComponentCloner.ComponentCloner()') Initialize a new instance of the ComponentCloner type.
        
    • Methods
      • Clone(Entity, Entity) Clones one Entity components to an other.
        
      • OnComponent<T>(T, bool) Handles the component of type T from the source Entity.
        
      • Set<T>(T, bool) Sets the given component on the copied entity.
        
    • EntityMap<TKey> Represents a collection of Entity mapped to a TKey component. Only one Entity can be associated with a given TKey.
      
    • Properies
      • Keys Gets the keys contained in the EntityMap<TKey>.
        
      • this[TKey] Gets the Entity associated with the specified key.
        
      • World Gets the World instance from which current EntityMap<TKey> originate.
        
    • Methods
      • [Complete()](EntityMap_TKey__Complete().md 'DefaultEcs.EntityMap<TKey>.Complete()') Clears current instance of its entities if it was created with some reactive filter ([WhenAdded<T>()](EntityQueryBuilder_WhenAddedT().md 'DefaultEcs.EntityQueryBuilder.WhenAdded<T>()'), [WhenChanged<T>()](EntityQueryBuilder_WhenChangedT().md 'DefaultEcs.EntityQueryBuilder.WhenChanged<T>()') or [WhenRemoved<T>()](EntityQueryBuilder_WhenRemovedT().md 'DefaultEcs.EntityQueryBuilder.WhenRemoved<T>()')).
        Does nothing if it was created from a static filter.
        This method need to be called after current instance content has been processed in a update cycle.
        
      • ContainsEntity(Entity) Determines whether the EntityMap<TKey> contains a specific Entity.
        
      • ContainsKey(TKey) Determines whether the EntityMap<TKey> contains the specified key.
        
      • [Dispose()](EntityMap_TKey__Dispose().md 'DefaultEcs.EntityMap<TKey>.Dispose()') Releases current EntityMap<TKey> of its subscriptions, stopping it to get modifications on the World's Entity.
        
      • [TrimExcess()](EntityMap_TKey__TrimExcess().md 'DefaultEcs.EntityMap<TKey>.TrimExcess()') Resizes inner storage to exactly the number of Entity this EntityMap<TKey> contains.
        
      • TryGetEntity(TKey, Entity) Gets the Entity associated with the specified key.
        

        Namespaces

        DefaultEcs Namespace

        The DefaultEcs namespace contains types to put in place the Entity Component System pattern.

Classes
AoTHelper	Provides a set of methods to help the generation of generic code for AoT compilation.
ComponentCloner	Exposes a way to clone one Entity components to an other.
EntityMap<TKey>	Represents a collection of Entity mapped to a TKey component. Only one Entity can be associated with a given TKey.

[Doraku]

Small example starting the summary on the same line as the page link to not take as much space:

• Namespaces
  • DefaultEcs The DefaultEcs namespace contains types to put in place the Entity Component System pattern.
    
  • Classes
    • AoTHelper Provides a set of methods to help the generation of generic code for AoT compilation.
      
    • Methods
      • [RegisterComponent<T>()](AoTHelper_RegisterComponentT().md 'DefaultEcs.AoTHelper.RegisterComponent<T>()') Registers the type [T](AoTHelper_RegisterComponentT().md#DefaultEcs_AoTHelper_RegisterComponentT()_T 'DefaultEcs.AoTHelper.RegisterComponent<T>().T') so it can freely be used in ComponentAttribute.
        
      • [RegisterMessage<T>()](AoTHelper_RegisterMessageT().md 'DefaultEcs.AoTHelper.RegisterMessage<T>()') Registers the type [T](AoTHelper_RegisterMessageT().md#DefaultEcs_AoTHelper_RegisterMessageT()_T 'DefaultEcs.AoTHelper.RegisterMessage<T>().T') so SubscribeAttribute can freely be used on method like the delegate MessageHandler<T>(T) to automatically subscribe when using IPublisherExtension on a World instance.
        
      • [RegisterUnmanagedComponent<T>()](AoTHelper_RegisterUnmanagedComponentT().md 'DefaultEcs.AoTHelper.RegisterUnmanagedComponent<T>()') Registers the unmanaged type [T](AoTHelper_RegisterUnmanagedComponentT().md#DefaultEcs_AoTHelper_RegisterUnmanagedComponentT()_T 'DefaultEcs.AoTHelper.RegisterUnmanagedComponent<T>().T') so it can freely be used in ComponentAttribute and by Set<T>(T).
        
    • ComponentCloner Exposes a way to clone one Entity components to an other.
      
    • Constructors
      • [ComponentCloner()](ComponentCloner_ComponentCloner().md 'DefaultEcs.ComponentCloner.ComponentCloner()') Initialize a new instance of the ComponentCloner type.
        
    • Methods
      • Clone(Entity, Entity) Clones one Entity components to an other.
        
      • OnComponent<T>(T, bool) Handles the component of type T from the source Entity.
        
      • Set<T>(T, bool) Sets the given component on the copied entity.
        
    • EntityMap<TKey> Represents a collection of Entity mapped to a TKey component. Only one Entity can be associated with a given TKey.
      
    • Properies
      • Keys Gets the keys contained in the EntityMap<TKey>.
        
      • this[TKey] Gets the Entity associated with the specified key.
        
      • World Gets the World instance from which current EntityMap<TKey> originate.
        
    • Methods
      • [Complete()](EntityMap_TKey__Complete().md 'DefaultEcs.EntityMap<TKey>.Complete()') Clears current instance of its entities if it was created with some reactive filter ([WhenAdded<T>()](EntityQueryBuilder_WhenAddedT().md 'DefaultEcs.EntityQueryBuilder.WhenAdded<T>()'), [WhenChanged<T>()](EntityQueryBuilder_WhenChangedT().md 'DefaultEcs.EntityQueryBuilder.WhenChanged<T>()') or [WhenRemoved<T>()](EntityQueryBuilder_WhenRemovedT().md 'DefaultEcs.EntityQueryBuilder.WhenRemoved<T>()')).
        Does nothing if it was created from a static filter.
        This method need to be called after current instance content has been processed in a update cycle.
        
      • ContainsEntity(Entity) Determines whether the EntityMap<TKey> contains a specific Entity.
        
      • ContainsKey(TKey) Determines whether the EntityMap<TKey> contains the specified key.
        
      • [Dispose()](EntityMap_TKey__Dispose().md 'DefaultEcs.EntityMap<TKey>.Dispose()') Releases current EntityMap<TKey> of its subscriptions, stopping it to get modifications on the World's Entity.
        
      • [TrimExcess()](EntityMap_TKey__TrimExcess().md 'DefaultEcs.EntityMap<TKey>.TrimExcess()') Resizes inner storage to exactly the number of Entity this EntityMap<TKey> contains.
        
      • TryGetEntity(TKey, Entity) Gets the Entity associated with the specified key.
        

[Doraku]

An other option, using label to remove the family indentation (Classes, Constructors, Fields, ...)

• DefaultEcs Namespace The DefaultEcs namespace contains types to put in place the Entity Component System pattern.
  
  • AoTHelper Classe Provides a set of methods to help the generation of generic code for AoT compilation.
    
  • [RegisterComponent<T>()](AoTHelper_RegisterComponentT().md 'DefaultEcs.AoTHelper.RegisterComponent<T>()') Method Registers the type [T](AoTHelper_RegisterComponentT().md#DefaultEcs_AoTHelper_RegisterComponentT()_T 'DefaultEcs.AoTHelper.RegisterComponent<T>().T') so it can freely be used in ComponentAttribute.
    
  • [RegisterMessage<T>()](AoTHelper_RegisterMessageT().md 'DefaultEcs.AoTHelper.RegisterMessage<T>()') Method Registers the type [T](AoTHelper_RegisterMessageT().md#DefaultEcs_AoTHelper_RegisterMessageT()_T 'DefaultEcs.AoTHelper.RegisterMessage<T>().T') so SubscribeAttribute can freely be used on method like the delegate MessageHandler<T>(T) to automatically subscribe when using IPublisherExtension on a World instance.
    
  • [RegisterUnmanagedComponent<T>()](AoTHelper_RegisterUnmanagedComponentT().md 'DefaultEcs.AoTHelper.RegisterUnmanagedComponent<T>()') Method Registers the unmanaged type [T](AoTHelper_RegisterUnmanagedComponentT().md#DefaultEcs_AoTHelper_RegisterUnmanagedComponentT()_T 'DefaultEcs.AoTHelper.RegisterUnmanagedComponent<T>().T') so it can freely be used in ComponentAttribute and by Set<T>(T).
    
  • ComponentCloner Classe Exposes a way to clone one Entity components to an other.
    
  • [ComponentCloner()](ComponentCloner_ComponentCloner().md 'DefaultEcs.ComponentCloner.ComponentCloner()') Constructor Initialize a new instance of the ComponentCloner type.
    
  • Clone(Entity, Entity) Method Clones one Entity components to an other.
    
  • OnComponent<T>(T, bool) Method Handles the component of type T from the source Entity.
    
  • Set<T>(T, bool) Method Sets the given component on the copied entity.
    
  • EntityMap<TKey> Classe Represents a collection of Entity mapped to a TKey component. Only one Entity can be associated with a given TKey.
    
  • Keys Property Gets the keys contained in the EntityMap<TKey>.
    
  • this[TKey] Property Gets the Entity associated with the specified key.
    
  • World Property Gets the World instance from which current EntityMap<TKey> originate.
    
  • [Complete()](EntityMap_TKey__Complete().md 'DefaultEcs.EntityMap<TKey>.Complete()') Method Clears current instance of its entities if it was created with some reactive filter ([WhenAdded<T>()](EntityQueryBuilder_WhenAddedT().md 'DefaultEcs.EntityQueryBuilder.WhenAdded<T>()'), [WhenChanged<T>()](EntityQueryBuilder_WhenChangedT().md 'DefaultEcs.EntityQueryBuilder.WhenChanged<T>()') or [WhenRemoved<T>()](EntityQueryBuilder_WhenRemovedT().md 'DefaultEcs.EntityQueryBuilder.WhenRemoved<T>()')).
    Does nothing if it was created from a static filter.
    This method need to be called after current instance content has been processed in a update cycle.
    
  • ContainsEntity(Entity) Method Determines whether the EntityMap<TKey> contains a specific Entity.
    
  • ContainsKey(TKey) Method Determines whether the EntityMap<TKey> contains the specified key.
    
  • [Dispose()](EntityMap_TKey__Dispose().md 'DefaultEcs.EntityMap<TKey>.Dispose()') Method Releases current EntityMap<TKey> of its subscriptions, stopping it to get modifications on the World's Entity.
    
  • [TrimExcess()](EntityMap_TKey__TrimExcess().md 'DefaultEcs.EntityMap<TKey>.TrimExcess()') Method Resizes inner storage to exactly the number of Entity this EntityMap<TKey> contains.
    
  • TryGetEntity(TKey, Entity) Method Gets the Entity associated with the specified key.
    

[Doraku]

sorry for the spam of big markdown, I don't know which one looks better and is more usable yet :/

[hairlesshobo]

I hate to be "that guy", but I like all the options lol. I could easily see cases where each style would be best. Perhaps you can create a few options to figure the output.. Something like OutputFullIndex to enable the generation in the first place. Then IndexIncludeSummary could toggle whether there is the summary included in the output. IndexElementTypeStyle could be an enum with the following

• None
• CategoryHeader (where the element types are grouped under category headers like the first 2 examples.)
• Tag (I don't know what to call it when you put the element type after the element itself, such as in the last example)

I'm a bit fan of options myself ;)

Hope what I'm saying make sense. Let me know if you need clarification.

[tihomir-kit]

I feel like having the option to remove descriptions would be good. Having all the descriptions could get too noisy in some situations.

[Doraku]

I hate to be "that guy", but I like all the options lol.

I feared that answer haha. The process is simple enough that it should be possible, here are the options I can see, defined in a flag enum:

• None (no index generated)
• Assembly (index generated on the assembly page)
• Namespace (index generated each namespace pages)
• ... (for each possible type, you get the idea)
• ShowSummary (shows the summary, with a line break)
• ShowInlinedSummary (shows the summary without a line break)
• ShowKindIndentation (shows the kind as a top level indentation like the first two, if not do like the third)
• ReplaceChildLinks (if defined the elements with their own page won't appear in the current table like display)

Some of those names are crappy but that's the direction I'm going. Now I am wondering if those settings should be specific for each page kinds instead of being shared for everything, I don't want to put too much settings/configuration like other solution (this is what led me to start this project at first and it is starting to grow just like them haha) but I can see people wanting different index display for different pages.

[tihomir-kit]

Do you need any help with this, if yes with what (if you direct me a bit into what you'd like to get done, I could spare a bit of time to do it)?

I don't mean to push you, I'm just wondering if you have any idea of a super rough timeline when you think you might publish this feature?

[Doraku]

Because I like doing too many things at the same time I am currently going through a big refactoring #90 that should open up a lot of possibilities in the futur ^^" I hope to finish it this week end and then move back to this feature.

[tihomir-kit]

Thank you!

[tihomir-kit]

Sorry to bother again, I was just wondering if there are any plans to put v0.8 out of alpha status soon-ish? Thnx

[Doraku]

hey sorry for the big delay, it should be out pretty soon. I "only" have to update the documentation before creating the release. There was a lot of big changes ^^"