This answer is intended to be progressively updated as I gain experience with this functionality myself. I assume you are using Wolfram Workbench and the documentation authoring tools it provides.
As the documentation describes, you need to make sure that your package(s) are in a proper directory structure for a Mathematica application. You can do this by initially selecting "Application" for the project type in Workbench. (File > New > Project)
If you already have packages, you need to move them into this structure, at the top level folder for the project. (I have obscured the project name here so as not to identify my employer.)
Right-click/control-click on one of the subfolders in the documentation folder tree, and choose New > Notebook File.
Once created you can right-click on that file to open in Mathematica. When Mathematica is launched in this way, it will include in the Pallettes menu an item for Documentation Tools.
From this you can click on the Utilities button to reveal the Generate Function Pages button. Clicking this will generate fresh documentation pages for all the functions and options defined in your package. It is also clever enough to trace through if your main package calls other custom packages and creates documentation for those objects as well. My current project has around 60 new functions and options; it took about three minutes to create all the pages.
However, for this to work well, it is essential that you have already defined good usage messages for all your functions and options defined in your packages. Usage messages have to start with the name of the function to be recognised properly: see the example in the screenshot below.
The pages themselves come out looking like this:
Obviously, in this instance, my DateListBarChart function builds on existing functionality and takes all the options that BarChart does.
If you scroll down these pages, you will find that they have sections designed specifically for examples that you can provide, and that the user can interact with.
To get the documentation into final form, you need to click the Build button in the Application Tools tab of Workbench’s Mathematica Development perspective. You can then click Deploy Application in the same tab to get package and bundle into a place on the $Path that Mathematica can find when it is running normally rather than in conjunction with Workbench.
Most of this information is in the Workbench documentation, but to be honest it isn’t particularly clear. The tip about making sure you have sensible usage messages wasn’t anywhere that I could find.
