Consider: documentation as a feature

[bleroy]

Modules can provide and embed their own documentation in two forms, code comments and markdown documents. In DecentCMS, documentation is a feature. The documentation web site is just an instance of the CMS with the documentation feature enabled. The feature has content providers for code comments and markdown docs under the docs subfolder of each module, and a navigation provider that generates navigation menus, breadcrumbs, etc. for all topics cross all modules. The content providers expose the API doc and markdown files as actual content items (which shows how the content type system shouldn't care much where items are actually stored).

The documentation for the documentation feature can be found here.

[agriffard]

This is a great idea. Let's try to add a first example, while we develop the content fields.

Goals : We want to be able to provide some technical and some user documentation that will help to extend or use the features.

Steps: At the root of the module, we add information in Readme.md Add a docs folder. Add other .md files, e.g: one file by type of field. Add pictures : screenshots of admin screens, ...

From the features (Modules page), if it has a Readme, make a link to an url that allows to display it. Generate a sub menu (affix menu on the right?) to display the other docs pages.

[agriffard]

For the generation of an Api reference based on code comments, may be we could take a look at DocFx, that is used for the ASP.NET docs.

[agriffard]

As a POC, I tried to create a documentation using mkdocs and it seems really easy. I just added a mdocs.yml, add some pages from the already existing README.md and configured some extensions and a material theme,

The result is really nice. It could be hosted with github pages (orchardcms.github.io/orchard2/...).

[agriffard]

I set up Github pages and deployed the doc site using this command: mkdocs gh-deploy (http://www.mkdocs.org/user-guide/deploying-your-docs/) and specifying the gh-pages in the Settings (https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/)

It is available here: http://orchardcms.github.io/Orchard2/

I don't really know how to configure it to be built automatically. May be I will try to create a doc project on readthedocs and be able to specify a webhook to generate a site and host it like the OrchardDoc repo.

Then, we could have a redirection to subdomain.orchardproject.net . We just need to find the good name, create the alias and the redirection.

[sebastienros]

If it's a command, we can include it in the CI scripts

[agriffard]

I made some changes to be able to build the docs on readthedocs. It is available here: http://orchardcore.readthedocs.io/en/latest/

If we want to use RTD and a custom theme, we have to copy the theme files and specify theme_dir in mkdocs.yml

[agriffard]

List of modules that could need some documentation:

• Resources: Libraries Credits
• Bag
• Flows
• Widgets
• Templates
• Admin: Filter, Menu
• Alias
• Autoroute
• HomeRoute
• Feeds
• Layers
• Lists
• Markdown: Remove information about Tokens
• Permissions
• Remote Publishing
• Settings
• Tenants
• Users

[agriffard]

I'd like to make a list of features provided by Orchard Core.

Please review it and tell me if I can create a specific page in documentation for this :

CMS Features

• Enable existing features or add your own modules to extend the application.
• Create your content types adding out of the box predefined Parts and Fields.
• Customize your site using themes with ASP.NET Razor or Shopify Liquid syntax.
• Define different layouts on the site and add widgets anywhere in your pages.
• Declare templates in admin that overrides the rendering of your content types.
• Edit your content with Wysiwyg or Mardown editors that can use Liquid filters.
• Get a live preview your content in separate window while editing it in the admin.
• Manage media folders, upload files and link to images with automatic resizing.
• Organize your contents and navigate in the site: Lists, Menus, Taxonomies, Urls, ...
• Search: Index your data in Sql or Lucene and query them using Liquid loops.

Global Features

• NuGet packages: Add reference in your application to bundle packages and configure Orchard Services.
• Multi tenant: Host multiple sites with only one instance and manage them separately.
• Deployment: Import/Export the data and the structure of your site with deployment plans.
• Performance: Handle many requests per second by default and even more with Response Cache.
• Security: Manage the Users, Roles and Permissions to give access to the Admin dashboard pages.
• Setup: Use different recipes to setup your site with initial features and content types using configurable steps and dynamic parameters.
• Storage: YesSQL allows you to store your contents in SQL Server, SQLite, MySQL or PostgreSQL as if it was a document database.

[agriffard]

Each documentation issue can be found with this label : https://github.com/OrchardCMS/OrchardCore/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation

[agriffard]

I made a docspreview branch in which I pasted the material theme i order to use it on ReadTheDocs and I tried many different changes in mkdocs.yml but it always returns errors on build, like a missing config.theme.language.

See failed builds on https://readthedocs.org/projects/orchardcore/builds/

[agriffard]

https://github.com/mkdocs/mkdocs/blob/master/docs/user-guide/deploying-your-docs.md#read-the-docs

To benefit from all of the [features] offered by Read the Docs, you will need to use the [Read the Docs theme][theme] which ships with MkDocs. The various themes which may be referenced in Read the Docs' documentation are Sphinx specific themes and will not work with MkDocs.

[agriffard]

I fixed an error for the language but there would still be many things to change in the material mkdocs theme to make it work on ReadTheDocs.

[agriffard]

I managed to host the documentation and generate it with MkDocs on an Azure Web App : https://orchardcoredocs.azurewebsites.net/ To do this, I needed to add specific .deployment and deploy.cmd file. However, I don't know how we can handle multiple branches because I can only connect to one repository for the deployment. We could may be create 2 sites connected to master and dev branches and point them to different subdomains like coredocs.orchardproject.net and devdocs.orchardproject.net.

[sebastienros]

Cool! Yes I think we can create two sites.

[agriffard]

Documentation will stay a continuous effort so I am closing this one. Each missing documentation could have its own issue to track it.

Reminder: To list the documentation issues, you can use this filter: https://github.com/OrchardCMS/OrchardCore/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation

About the inital issue raised by Bertrand: if a feature is implemented to benefit from the md files in each module, it could be an interesting addition.