cduce issueshttps://gitlab.math.univ-paris-diderot.fr/cduce/cduce/-/issues2022-05-02T16:33:40+02:00https://gitlab.math.univ-paris-diderot.fr/cduce/cduce/-/issues/30RFC: Documentation and website2022-05-02T16:33:40+02:00MattiasRFC: Documentation and websiteSo, 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` from `site.cd`
- Run `site.cdo` on an ...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` from `site.cd`
- Run `site.cdo` on an xml file
- When my [MR](https://gitlab.math.univ-paris-diderot.fr/cduce/website/-/merge_requests/1) 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](https://gitlab.math.univ-paris-diderot.fr/cduce/cduce/-/blob/dev/web/dune) and in [website/Makefile](https://gitlab.math.univ-paris-diderot.fr/cduce/website/-/blob/main/Makefile).
- The former (obtained with `dune build @website`) runs `site.cdo` on [cduce/web/doc.xml](https://gitlab.math.univ-paris-diderot.fr/cduce/cduce/-/blob/dev/web/doc.xml) and generate the doc in `./_build/default/web/doc`
- The latter (obtained with `make` in the cduce-website directory) runs `site.cdo` on [website/web/index.xml](https://gitlab.math.univ-paris-diderot.fr/cduce/website/-/blob/main/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](https://www.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](https://gitlab.math.univ-paris-diderot.fr/cduce/website/-/blob/main/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)
Discussion is now opened @kn and @beppehttps://gitlab.math.univ-paris-diderot.fr/cduce/cduce/-/issues/27Wrong explanation for the merge of the two records2022-03-16T17:18:12+01:00Giuseppe CastagnaWrong explanation for the merge of the two recordsThe current explanation for the merge is not correct:
```
val merge : t -> t -> t
(** [merge t1 t2] discards the non record component of [t1] and [t2] and
returns the type of the [+] operators on records, that is, returns a record...The current explanation for the merge is not correct:
```
val merge : t -> t -> t
(** [merge t1 t2] discards the non record component of [t1] and [t2] and
returns the type of the [+] operators on records, that is, returns a record
type [t] where the type of label [l] is the one of [t2] if it is present in
[t2] and the type of [t1] otherwise.
*)
```
Actually, this does not cover when l is optional in t1. If this is the case then it is the union of the two types
Formally
(t1 + t2)[l] = (t1[l]\undef)|t2[l] for undef < t1[l]https://gitlab.math.univ-paris-diderot.fr/cduce/cduce/-/issues/6Git subtree merge needed2017-10-16T08:48:07+02:00Kim NguyễnGit subtree merge neededSince the migration to Git the _website_ and cduce are in two distinct repositories. As a consequence the documentation that is in cduce/web and that is distributed with the language is no longer in synchro with the one one the website, ...Since the migration to Git the _website_ and cduce are in two distinct repositories. As a consequence the documentation that is in cduce/web and that is distributed with the language is no longer in synchro with the one one the website, which is the one up-to-date.
Solution: partially reorganize the files so that the directories manual tutorial examples img are directly taken by a subtree merge from the website gitGiuseppe CastagnaGiuseppe Castagna