Introduction
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.
Prerequisites
- 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
Let's explain 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:
{
"Title": "Documentation",
"Author": "RHEA System S.A.",
"PagePath": "home.md",
"Sections": [
{
"Name": "Getting Started",
"PagePath": "getting-started.md"
},
{
"Name": "How does it work",
"Sections": [
{
"Name": "Searches",
"PagePath": "searches.md"
},
{
"Name": "Configuration",
"Sections": [
{
"Name": "Configuration",
"PagePath": "Configuration\\configuration.md"
}
]
}
],
"PagePath": "how-does-it-work.md"
},
{
"Name": "License",
"PagePath": "license.md"
},
{
"Name": "Support",
"Sections":[],
"PagePath": "support.md"
}
]
}
The code gives the following hierarchy:
Let's explain the code:
In DocuPanel
, each entity of the treeView
is called a section
. 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 section
s, 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 Configuration
.
The parameters Title
and Author
can be set only once because they give information about the whole documentation.
Each section has the parameters Name
, Sections
, 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 License
section.
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:
<docuPanel:DocumentationView
PathDocumentationIndex="C:\Projects\DocuPanel\DocuPanelSupport\bin\x64\Debug\Documentation\book.json"
RootAppData="Users\<userName>\AppData\Local\<YourAppDataFolder>"
UpdateIndexation="true"/>
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.
If true
, 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.
Conclusion
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.
References
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.