(doc) how to generate odoc .mld documentation pages with dune (#1882)

* add a section on how to generate odoc documentation pages with dune
* minor formatting fixes

---------

Co-authored-by: Christine Rose <[email protected]>

Author: sabine

data/tutorials/platform/bp_08_odoc.md

@@ -6,7 +6,7 @@ description: |
 category: "Best Practices"
 ---
 
-# Generating Documentation With Odoc
+# Generating Documentation With `odoc`
 
 The documentation rendering tool `odoc` generates documentation
 in the form of HTML, LaTeX, or man pages,
@@ -23,3 +23,25 @@ $ open _build/default/_doc/_html/index.html
 # Windows
 $ explorer _build\default\_doc\_html\index.html
 ```
+
+## Generating `.mld` Documentation Pages
+
+In addition to documenting the publicly-visible API of your project,
+`odoc` also gives you the ability to add individual documentation pages.
+
+For example, to replace the automatically generated documentation
+index file, you have to add a file `index.mld` to your project.
+
+To make Dune find your `.mld` pages and process them with `odoc`,
+the `dune` file in the same directory as your `.mld` files needs to
+include this stanza:
+
+```
+(documentation
+ (package name-of-your-package))
+```
+
+A common place to put `.mld` files is a folder named `doc` or `docs`.
+
+For more information on how to write documentation pages for `odoc`,
+see the [`odoc` for authors documentation](https://ocaml.github.io/odoc/odoc_for_authors.html#doc-pages).