When you develop an application, you also probably write a user manual or a documentation to explain how your software works. You have the possibility to store it on the internet or include it directly in your application. If you choose to integrate your documentation in your software, you will spend quite a lot of time to create a view and build a structure which displays correctly the help.
Fortunately for you, a tool exists and makes the job for you.
DocuPanel is an open source project which integrates properly and quickly your Markdown documentation in your WPF application. It's a package that you can add to your application which browses your documentation files to index and analyze them in order to provide a
UserControl you can add to your view.
This article aims to explain step by step how to add
DocuPanel and how to make it work with your own documentation.
To have a better understanding of the project, you can read the documentation.
The source code is maintained on GitHub.
- Install the NuGet DocuPanel.
- Modify the platform in your configuration manager to be x64.
- A documentation written in Markdown.
DocuPanel uses the Chromium Browser CefSharp, that is why your application has to be x64 and not Any CPU or x86. However, you can also download the source code and build it in x86.
Usage By An Example
DocuPanel with an example. The source code of this example is also available on GitHub.
Step 1 - Add your Help Files in Your Project
It is also possible to create a subdirectory so that you can organize your files the way you want, here we have created a folder Configuration which contains the configuration.md file.
It's really important that each file has a unique name.
Step 2 - Create Your index json File
In order to know the architecture of the documentation and how to display its pages, we need to create an index file which contains all this information.
The content of book.json for this example is the following code:
"Author": "RHEA System S.A.",
"Name": "Getting Started",
"Name": "How does it work",
The code gives the following hierarchy:
Let's explain the code:
DocuPanel, each entity of the
treeView is called a
section can be associated to the path of a Markdown file, in this case when the user will select this
section, the page associated will be displayed. A
section can contain other
sections, here How does it work and Configuration contain subesctions, that is why they appear with a folder icon. In the Json file, the attribute
Sections appears with the subsections inside.
The other sections appear with a green page because they only contain a page associated.
Title is the title of your documentation.
Author is the author of the documentation. Can be empty.
PagePath is the relative path of the page associated to the section. Note that a
section does not necessary contain
PagePath. For example, a section can contain only children pages, it's what happens with
Configuration in our example.
Sections is the list of the subsections.
Name is the name displayed by
DocuPanel. It is possible to have two sections with the same name, in this example, we have two sections with the name
Author can be set only once because they give information about the whole documentation.
Each section has the parameters
PagePath. If a parameter is empty, you are not obligated to write it. In the previous code, we wrote
"Sections": for the
Support section, but we didn't write anything for the
Step 3 - Add DocuPanel to Your View
Our example project contains a view which is a simple Window. To integrate
DocuPanel, we add the following XAML code:
PathDocumentationIndex: Property of type
string which corresponds to the path of the index file of your documentation. As I remember, it must be at the root of the doc.
RootAppData: Property of type
string which corresponds to the path of the application data folder of your application.
DocuPanel will create on this path a directory called DocuPanel to store its datas.
UpdateIndexation: Property of type
bool which indicates whether the indexation needs to be updated.
DocuPanel will browse all the files indicated in the index, and will convert them into HTML if they don't already exist.
DocuPanel converts your Markdown files into HTML files to be displayed by
CefSharp. The indexation for the searches will also be updated with the new documentation content. Note that if you want to update the content of a file, to consider the changes you have to delete the HTML file from the application data folder.
This property needs to be
true the first time you use
DocuPanel and each time you make changes in your documentation.
In the example, the properties are bound to a view-model to show how we can dynamically change the values using the pattern MVVM.
You should now see
DocuPanel in your view, be able to browse the different pages and perform searches. I hope this tutorial has helped you to integrate this project to yours.
If you encountered some issues during this tutorial or during your utilization, let us know.
DocuPanel is used in the Concurrent Design Platform 4 and other projects of the RHEA GROUP.
The following tools are used in the project:
Points of Interest
DocuPanel is my first contribution to an open source project and I enjoyed developing the initial version. If you have any idea to improve it, your help is welcome. Feel free to contribute and don't hesitate to contact us or create a pull request.