WIP: Add a manual using odoc and .mld files#355
Draft
NathanReb wants to merge 6 commits intorealworldocaml:mainfrom
Draft
WIP: Add a manual using odoc and .mld files#355NathanReb wants to merge 6 commits intorealworldocaml:mainfrom
.mld files#355NathanReb wants to merge 6 commits intorealworldocaml:mainfrom
Conversation
412c257 to
6130320
Compare
christinerose
suggested changes
Jan 26, 2022
christinerose
left a comment
There was a problem hiding this comment.
I've added some minor line editing, as well as grammar and syntax suggestions. Please let me know if you're looking for a different type of feedback as well.
|
|
||
| Welcome to the MDX Manual! | ||
|
|
||
| MDX is a tool to help developpers and authors keep their documentation |
There was a problem hiding this comment.
Suggested change
| MDX is a tool to help developpers and authors keep their documentation | |
| MDX is a tool to help developers and authors keep their documentation |
| It ensures that the code examples you write compile and behave the way you | ||
| expect them to by actually running them. | ||
|
|
||
| It is for example used to verify all of |
There was a problem hiding this comment.
Suggested change
| It is for example used to verify all of | |
| For example, you can use MDX to verify all |
| It is for example used to verify all of | ||
| {{:https://dev.realworldocaml.org/}Realworlocaml}'s examples! | ||
|
|
||
| MDX is released on opam. You can install it in your switch by running: |
There was a problem hiding this comment.
Suggested change
| MDX is released on opam. You can install it in your switch by running: | |
| MDX is released on Opam, so you can install it in your switch by running: |
|
|
||
| {1 Basic Usage} | ||
|
|
||
| You can use MDX with your Markdown or [.mli] documentation, where it will ensure |
There was a problem hiding this comment.
Suggested change
| You can use MDX with your Markdown or [.mli] documentation, where it will ensure | |
| You can use MDX with your Markdown or [.mli] documentation, which ensures |
| {1 Basic Usage} | ||
|
|
||
| You can use MDX with your Markdown or [.mli] documentation, where it will ensure | ||
| the correctness of code respectively written in multi-line code blocks and |
There was a problem hiding this comment.
Suggested change
| the correctness of code respectively written in multi-line code blocks and | |
| correct code written in multiline code blocks and |
Comment on lines
12
to
101
| This label allows you to assign an environment to an OCaml block. That means | ||
| you benefit from whole the code that has been previously evaluated in that | ||
| environment, be it from other code blocks or {{!page-preludes}preludes}. |
There was a problem hiding this comment.
Suggested change
| This label allows you to assign an environment to an OCaml block. That means | |
| you benefit from whole the code that has been previously evaluated in that | |
| environment, be it from other code blocks or {{!page-preludes}preludes}. | |
| This label allows you to assign an environment to an OCaml block. That means | |
| you benefit from all the previously evaluated code in that | |
| environment, be it from other code blocks or {{!page-preludes}preludes}. |
Comment on lines
+20
to
+108
| The environement label expects a single string value which corresponds to the | ||
| name of the environment to use. |
There was a problem hiding this comment.
Suggested change
| The environement label expects a single string value which corresponds to the | |
| name of the environment to use. | |
| The environment label expects a single string value that corresponds to the current environment's name. |
Comment on lines
+49
to
+137
| When absent, the block will be evaluated in the default environment, e.g. | ||
| the environment shared by all blocks without an [env] label. |
There was a problem hiding this comment.
Suggested change
| When absent, the block will be evaluated in the default environment, e.g. | |
| the environment shared by all blocks without an [env] label. | |
| When absent, the block will be evaluated in the default environment, e.g., | |
| the environment shared by all blocks without an [env] label. |
Comment on lines
+3
to
+6
| Preludes are fragments of code that can be evaluated ahead of running the | ||
| code in OCaml and OCaml toplevel MDX blocks. They can be used to globally | ||
| open modules, register toplevel printers, set some globals like | ||
| [Printexc.record_backtrace], you name it! |
There was a problem hiding this comment.
Suggested change
| Preludes are fragments of code that can be evaluated ahead of running the | |
| code in OCaml and OCaml toplevel MDX blocks. They can be used to globally | |
| open modules, register toplevel printers, set some globals like | |
| [Printexc.record_backtrace], you name it! | |
| Preludes are fragments of code that can be evaluated ahead of running the | |
| code in OCaml and OCaml toplevel MDX blocks. They can globally | |
| open modules, register toplevel printers, set some globals like | |
| [Printexc.record_backtrace], and more! |
Comment on lines
+8
to
+10
| They are especially useful if you want to hide or share this kind of setup | ||
| phase, e.g. if you are writing polished documentation you want to publish | ||
| or you are using MDX to add tests in your mli files directly. |
There was a problem hiding this comment.
Suggested change
| They are especially useful if you want to hide or share this kind of setup | |
| phase, e.g. if you are writing polished documentation you want to publish | |
| or you are using MDX to add tests in your mli files directly. | |
| They are especially useful if you want to hide or share this kind of setup | |
| phase, e.g., you want to publish polished documentation | |
| or you are using MDX to add tests directly in your [mli] files. |
NathanReb
added a commit
to NathanReb/mdx
that referenced
this pull request
Feb 28, 2022
This is a temporary update until we get the manual in realworldocaml#355 merged Signed-off-by: Nathan Rebours <nathan.p.rebours@gmail.com>
This introduce a new, more explicit labels `block-type=...` which is meant to replace the four separate labels `cram`, `ocaml`, `toplevel` and `include` in the future. It is added for a transition period at the end of which the four labels of the apocalypse should be removed in favor of this new one. Signed-off-by: Nathan Rebours <nathan.p.rebours@gmail.com>
Signed-off-by: Nathan Rebours <nathan.p.rebours@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Signed-off-by: Nathan Rebours <nathan.p.rebours@gmail.com>
Signed-off-by: Nathan Rebours <nathan.p.rebours@gmail.com>
52c4e7d to
dfc13b6
Compare
Draft
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.