Create end user documentation

[tsahi]

Is your feature request related to a problem? Please describe.
The only usage documentation available today is for EntLib 6.0 on MSDocs. We should have our own copy, that we can maintain and update with new features.

Describe the solution you'd like
We need both simple usage documentation, in a tutorial form, and API reference generated from XML comments in code. The simplest way to publish them would be to GitHub Pages.

I suggest we start with the tutorial page currently on MSDocs, and update it as necessary.

There are a number of documentation generators that can create documentation out of code comments, as well as general content pages.

Doxygen

Extracts code comments and generates HTML by templates. Some features require custom syntax in the comments. Content pages are generated from code pages that contain comments only. Relatively fast.

DocFx

By Microsoft. The tool used to generate MSDocs pages. Supports Markdown for content pages, which can make it easier to use.

Sandcastle

Also works. Uses reflection to extract the comments, which makes it relatively slow.

Describe alternatives you've considered
I'm open to any other documentation solution, but I think this will be important for the 7.0 milestone.

Additional context
We should probably ask Microsoft for permission to use their content.

[tsahi]

there is also https://readthedocs.org/

[tsahi]

From what I understand from the GitHub Pages docs, in order to create a site, we need to:

1. create a repository named enterpriselibrary.github.io owned by the EnterpriseLibrary organization
2. the root of that repository contains the source (static HTML/images/js/CSS etc.) for the organization site.
3. assuming we want the organization site to be common to all projects, the docs for a project are stored at the root of a gh-pages branch. This can be configured in the settings to the default (master) branch, under the /docs folder, which look more reasonable to me, because any branch will also contain all of the C# source files. Project content is published to a / folder in the organization site.

Content can be markdown files, which are automatically converted to HTML by the GitHub build process using Jekyll.

And then we want to publish API reference from the code comments, using one of the tools above. This means that content will have to be pushed to the repo, either manually or by the build process.

@Chavoshi

[tsahi]

MicrosoftDocs/feedback#3482

[tsahi]

Basically this is the last issue remaining before releasing DAAB 7.

[tsahi]

@Chavoshi @mjrousos While we wait on Microsoft to reply to the issue I linked above, which in my experience can take months, how about starting with uploading the API docs from the XML comments, using one of the tools above, and some basic configuration documentation?
As far as I'm concerned, my work on DAAB 7.0 is done, and I'm only waiting for the docs to be available to users. Remaining issues are non-breaking, and can be done in 7.1 and later.

[tsahi]

I started playing around with Doxygen, which is easy to setup and configure. It needs some fine tuning, but here's some basic result:

[tsahi]

Hi @Chavoshi @turabek @moein-shafiei @mjrousos I've put allot of effort into the rewrite of the package, and I'd really want to see it go out to users, But I don't think this can be done without proper documentation, especially considering the significant API change. I'm willing to write this documentation myself, but I need a platform to write it on. I think the best option is GitHub Pages, but I can consider anything. Please move this forward somehow.

[Chavoshi]

Hi @tsahi,
I am OK with either Doxygen or GitHub Pages, please let me know how can I help you to continue.

[tsahi]

https://docs.github.com/en/pages

From what I understand from the GitHub Pages docs, in order to create a site, we need to:

1. create a repository named enterpriselibrary.github.io owned by the EnterpriseLibrary organization
2. the root of that repository contains the source (static HTML/images/js/CSS etc.) for the organization site.
3. assuming we want the organization site to be common to all projects, the docs for a project are stored at the root of a gh-pages branch. This can be configured in the settings to the default (master) branch, under the /docs folder, which look more reasonable to me, because any branch will also contain all of the C# source files. Project content is published to a / folder in the organization site.

Content can be markdown files, which are automatically converted to HTML by the GitHub build process using Jekyll.

And then we want to publish API reference from the code comments, using one of the tools above. This means that content will have to be pushed to the repo, either manually or by the build process.

@Chavoshi

[tsahi]

@Chavoshi any progress?

[Chavoshi]

@tsahi , sorry for the late action, I've created the repository and made you admin there, please let me know if you need anything else from me.

[tsahi]

I committed the Doxygen output to the EnterpriseLibrary.github.io repo, and it's now visible on the site. I'm not very happy with the Doxygen layout, mainly because it treats namespaces as containers for lower-level namespaces, similar to Java packages. In C#, namespaces are containers for types, and containers that don't have types in them don't really exist. This makes it less intuitive to the C# developer in my view. But it's the easiest system to set up and run under CI/CD, so I stayed with it. I may try to further customize it later on.

I still haven't received a real response on MicrosoftDocs/feedback#3482, so I'll start writing some basic conceptual content on how to use DAAB, so people know how to deploy it.

[tsahi]

Since this is taking too long, I'll create the PR now, and continue with this issue later.
I created a migration guide from 6.* to 7.0.

[tsahi]

And with that PR, a global pandemic and local political turmoil later, we have everything ready for a RC1 release. We only need to figure out the new packages names. Will microsoft let us use the EnterpriseLibrary prefix, or would we use a new one?

[Chavoshi]

Most probably we have to come up with a new prefix as seems Microsoft is not cooperating 👎🏻
Cheers anyway for all the efforts 👍🏻
We can plan the release next week, if you're good with it.

[tsahi]

Sorry I didn't see this earlier. But we can release any time you want, as soon as we rename in build script and documentation. How about the prefix "EntLib"? can we take ownership on this prefix?

[tsahi]

@Chavoshi ?

[feiazifeiazi]

加油。