WIP: Add a manual using odoc and `.mld` files #355

NathanReb · 2021-11-05T17:57:42Z

No description provided.

christinerose

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.

christinerose · 2022-01-26T08:05:50Z

doc/index.mld

+
+Welcome to the MDX Manual!
+
+MDX is a tool to help developpers and authors keep their documentation


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

christinerose · 2022-01-26T08:07:44Z

doc/index.mld

+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


Suggested change

It is for example used to verify all of

For example, you can use MDX to verify all

christinerose · 2022-01-26T08:08:26Z

doc/index.mld

+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:


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:

christinerose · 2022-01-26T08:08:55Z

doc/index.mld

+
+{1 Basic Usage}
+
+You can use MDX with your Markdown or [.mli] documentation, where it will ensure


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

christinerose · 2022-01-26T08:12:07Z

doc/index.mld

+{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


Suggested change

the correctness of code respectively written in multi-line code blocks and

correct code written in multiline code blocks and

christinerose · 2022-01-26T08:31:37Z

doc/labels.mld

+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}.


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}.

christinerose · 2022-01-26T08:34:02Z

doc/labels.mld

+The environement label expects a single string value which corresponds to the
+name of the environment to use.


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.

christinerose · 2022-01-26T08:34:25Z

doc/labels.mld

+When absent, the block will be evaluated in the default environment, e.g.
+the environment shared by all blocks without an [env] label.


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.

christinerose · 2022-01-26T08:35:33Z

doc/preludes.mld

+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!


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!

christinerose · 2022-01-26T08:37:05Z

doc/preludes.mld

+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.


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.

This is a temporary update until we get the manual in realworldocaml#355 merged Signed-off-by: Nathan Rebours <[email protected]>

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 <[email protected]>

Signed-off-by: Nathan Rebours <[email protected]>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Signed-off-by: Nathan Rebours <[email protected]>

NathanReb added the no changelog This PR doesn't require a changelog update label Nov 8, 2021

NathanReb force-pushed the mdx-manual branch 2 times, most recently from 412c257 to 6130320 Compare November 10, 2021 11:14

christinerose suggested changes Jan 26, 2022

View reviewed changes

NathanReb added a commit to NathanReb/mdx that referenced this pull request Feb 28, 2022

Update README with mli compatibility and dune stanza reference

4a0b817

This is a temporary update until we get the manual in realworldocaml#355 merged Signed-off-by: Nathan Rebours <[email protected]>

NathanReb mentioned this pull request Feb 28, 2022

Update README with mli compatibility and dune stanza reference #370

Merged

NathanReb force-pushed the mdx-manual branch from 6130320 to 52c4e7d Compare July 21, 2022 08:18

NathanReb and others added 6 commits August 3, 2022 17:25

Rename block-type label to type

53bfb95

Signed-off-by: Nathan Rebours <[email protected]>

Update CHANGES.md

64cd796

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Fix doc comments

426bd17

Signed-off-by: Nathan Rebours <[email protected]>

TMP: Add an MDX manual using odoc .mld files

dad5f33

Signed-off-by: Nathan Rebours <[email protected]>

tmp

dfc13b6

NathanReb force-pushed the mdx-manual branch from 52c4e7d to dfc13b6 Compare September 16, 2022 09:58

sorawee mentioned this pull request Dec 2, 2023

Revamp README #442

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: Add a manual using odoc and `.mld` files #355

WIP: Add a manual using odoc and `.mld` files #355

NathanReb commented Nov 5, 2021

christinerose left a comment

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022

christinerose Jan 26, 2022


		Welcome to the MDX Manual!

		MDX is a tool to help developpers and authors keep their documentation

	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 is for example used to verify all of
	For example, you can use MDX to verify all

	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

	the correctness of code respectively written in multi-line code blocks and
	correct code written in multiline code blocks and

		The environement label expects a single string value which corresponds to the
		name of the environment to use.

	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.

		When absent, the block will be evaluated in the default environment, e.g.
		the environment shared by all blocks without an [env] label.

WIP: Add a manual using odoc and .mld files #355

Are you sure you want to change the base?

WIP: Add a manual using odoc and .mld files #355

Conversation

NathanReb commented Nov 5, 2021

christinerose left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

WIP: Add a manual using odoc and `.mld` files #355

WIP: Add a manual using odoc and `.mld` files #355