RFC: Documentation and website
So, I may not understand everything but let's try to summarise what I understand.
The way to produce documentation is to produce the website. This will do the following things:
- Compile
site.cdo
fromsite.cd
- Run
site.cdo
on an xml file - When my MR is merged, run
dune build @doc
to generate the api and copy/paste the files in the html directory
First issue
Issue
This is done in cduce/web/dune and in website/Makefile.
- The former (obtained with
dune build @website
) runssite.cdo
on cduce/web/doc.xml and generate the doc in./_build/default/web/doc
- The latter (obtained with
make
in the cduce-website directory) runssite.cdo
on website/web/index.xml and generate the doc in/tmp/public_html.$(LOGNAME)
Solution
Let's get rid of website/web
and generate all the website like my MR generates the API (see https://gitlab.math.univ-paris-diderot.fr/cduce/website/-/blob/cduce_api/Makefile#L10 and https://gitlab.math.univ-paris-diderot.fr/cduce/website/-/blob/cduce_api/Makefile#L25)
What I do here is create a git submodule containing the cduce repository, call dune build @doc
inside it and copy/paste it to the proper directory (here /tmp/public_html.$(LOGNAME)
)
Why is this my preferred solution?
The reason is simple: when someone makes a MR that changes the behaviour of CDuce (by adding new features, deprecating things etc), they can immediately edit the corresponding part of the documentation in the same MR since everything is in the CDuce repository. From the website repository perspective, we just need to update the submodule (that should always link to the main
branch of CDuce since this is the production branch)
Second issue
Let's focus on the website part since this is the one that generates cduce.org hoping it will be merged in the cduce repository and use it as a submodule.
Issue
The documentation is split between the API (generated with dune build @doc
) and the rest (generated from all the xml files). This may make it hard for contributions since you need to edit .mli
files and .xml
files if you made some breaking changes.
Solution
This is not an easy task and I honestly don't think it's useful but just to plant a seed and see how it grows.
Some parts of the documentation could be generated from the .mli
files by extracting some parts of the comments. The thing I like about this is that we can improve the direct documentation (the .mli
files) by adding examples in it that can be reused for the website.
What I dislike about it, it's not easy to do, it demands some hardwork in .mli
files for contributions.
Right now, I'd say don't touch this part.
Third issue
Issue
If we want to add more html tags we need to update cduce/web/siteTypes.cd.
Solution
I'm not an expert in XML but would we be able to allow the use of <![CDATA[ valid html ]]>
in XML files?
Small issues
-
odoc
produces its own css file that hardly fits other website css so maybe we should create our own css file for the generated api (just remember to delete their odoc.css and replace it with our own) - The website could go through an update (css, google search bar, site map, night mode etc)
- Inline
cduce.js
in the website for the examples (This reminds me of the "protected functions" in CDuce, if someone could create an issue about it)