Begin new odoc manuals #203

leostera · 2018-09-26T10:00:28Z

Opening this to gather early feedback and comments 🗣

I feel it's mandatory for odoc, since it's goal is to generate documentation, to bootstrap it's own. So odoc is documented using odoc.

Hence I'm opening this PR. I started writing a new index manual, but i'd like a few more things to get done before we merge it.

For the time being I'm hosting it here: https://ostera.github.io/odoc/

TO DO

Follow-up Work

Point .md files in repo to docs
Make sure all references to the modules are correct
Make sure all flows are correct
Proofread
Table of Contents is generated
Odoc Internals: In-depth flow of html generation

leostera · 2018-09-26T10:01:55Z

cc @aantron @rizo

rizo · 2018-09-26T16:40:30Z

src/odoc/page-index.mld

@@ -0,0 +1,252 @@
+{1:top odoc}
+
+The documentation compiler for OCaml, Reason, and BuckleScript.


Does BuckleScript belong here? You could as well say dune in that case. Any tool can use odoc really, I'd keep just "OCaml and Reason".

As long as we convey properly that this can be used with BuckleScript compilation units, I'm up for rephrasing.

It's not obvious to everyone, particularly since Reason can be used with the OCaml toolchain.

I think this can be explained later, i.e., the fact that odoc is designed to be integrated into existing build toolchains like BuckleScript and dune. A "documentation compiler" operates on syntax; BuckleScript is a compiler, that's why I find it confusing.

Also, ideally the end users shouldn't worry about how odoc works at all. That's why I think it's important to have a separate guide that describes the documentation features for documentation authors.

rizo · 2018-09-26T16:41:46Z

src/odoc/page-index.mld

+
+{2:overview What is [odoc] really?}
+
+[odoc] is not your regular documentation tool.


I'd mention that it's designed to be build-tool friendly. With focus on parallelism, caching, etc. I don't mind adding those changes separately though.

Rather than "regular" I'd say "ordinary". We hope it becomes everyone's regular tool. :)

rizo · 2018-09-26T16:46:03Z

src/odoc/page-index.mld

+|> map ~f:compile_to_odoc  (* here we have Game.odoc, Player.odoc, etc *)
+|> iter ~f:compile_to_html (* here we have Game/index.html, and so on  *)
+
+]}


Wouldn't it be better to show this in shell syntax? Otherwise people will assume there's actually an OCaml API for this.

rizo · 2018-09-26T16:46:40Z

src/odoc/page-index.mld

+on compiler outputs and turns them into compiled documentation, which then
+becomes gorgeous HTML.
+
+A regular [odoc] execution transforms [cmt], [cmti], and [mld] files into [odoc]


Maybe you can explain what odoc files are before mentioning them here? Surely people will ask "what is an odoc file?".

rizo · 2018-09-26T16:48:00Z

src/odoc/page-index.mld

+
+{[
+# We must tell odoc what the name of this Package is!
+λ odoc compile --package Game -o ./src/Player.odoc ./src/Player.cmti


Just a minor thing, but $ would look more familiar to most people.

rizo · 2018-09-26T16:48:56Z

src/odoc/page-index.mld

+Now we can compile this to an HTML file:
+
+{[
+λ odoc html -I src -o . ./src/Player.odoc


The -o is very important. I would explain that it's typically the root path of the generated documentation for a package.

rizo · 2018-09-26T16:54:15Z

Don't have time to do a thorough review but I like the idea in general.

I would try to clarify who is the target audience for the manual sections. For example, the low-level compilation information is IMO only useful for people who need to integrate odoc into a build tool – I would try to make it more formal and less example-driven.

Alternatively, for end users, it's more important to know how to write good documentation with the available features (pages, indexes, references, etc).

grabbou · 2018-09-26T20:20:03Z

Thank you very much for taking care of this! If there's anyway I can help or get involved, please let me know!

It took me a really long time to figure out the process of building a documentation website with odoc. Great that it will be all in one place from now.

Alternatively, for end users, it's more important to know how to write good documentation with the available features (pages, indexes, references, etc).

I can only speak for myself, but I wish I knew all that upfront.

aantron · 2018-09-26T22:35:12Z

Agreeing with @rizo here, the text so far is for people doing build system integration (and we do need that text). Hopefully, fewer and fewer end users will need to see this over time. odoc developers will always need this.

rizo · 2018-09-27T10:19:59Z

One extra comment about the name change from index.mld to page-index.mld: dune treats the index.mld file in a special way – it's used to produce the module index page. For that reason and because the page-* prefix is only required for .odoc files I don't recommend renaming the file. Thus for consistency other documentation pages should also avoid the prefix. I also find it redundant anyway, the fact that the file is a page is already clear from the extension.

leostera · 2018-10-09T08:35:18Z

I split the manual into smaller pieces that we can extend independently over time: https://ostera.github.io/odoc/Odoc/

However, I don't expect this PR to elaborate on all of them immediately, so I'll mark the Manuals in the TODO list as done.

Over the next few days I'll get the build+publish process in place, and then we can review more easily.

leostera · 2018-10-09T19:45:11Z

@aantron @rizo thoughts on running make docs on every commit? pre-commit hook that can be setup? keep it manual for now?

If we keep it manual and use the master branch's docs folder then I can check those two TODO's off ✅

leostera · 2018-10-09T21:22:20Z

I included the necessary travis config to build and deploy on every commit that makes it to master. It's straightforward to drop if we decide to manually publish docs 👍

leostera · 2018-10-09T21:24:41Z

.travis.yml

@@ -8,6 +8,8 @@ env:
  - OCAML=4.05.0
  - OCAML=4.06.1
  - OCAML=4.07.0
+  global:
+    secure: jMXf4/x4WZdgYARkH9CEq/zk58fPhiRzUwysBzSSA1f+tb8uRGNaMukZ41tdCsTdH2AckVw8Q5CHDD8RZCtAwftZjOHjjocvPlRtCEtXwy9qri5+a9g3dqMj/0WMW4YUt0Z9oSAXfjObL7vKKTNUx/aZASLx9+vLJNGUYVfhtOWVBiWc9PuAaE+TYKcE4gY43OihgpEy2QK/O/wSkfY2eaf7rsWGMSS/re2dtaBsl9CS2Z8IcWarSfl9+KajDejU2ciTfKwK5JKGx6pSG6We3qj7hNl+zRQJCXsEVflqon8/K/HReFbwoFJ4iRcs3lAQ56sVKzYhhLyCKbGywgZPl3GmhwM+NSLpWeh9KQTbkBEQFK+8J6qRWSYsjaZktbIZIOjYRf+rAwSRdmRnI3rNppP02oxTgi5fBZV+t+3SjLsHZqfzutuAphED23Pj2nu0GUABNzFYV+XkracZFiiTQeWPb5iH2SC334pL+KmY6Dsp8JyP2Kq8NpOsZo8085368Nlkr2EERSrhWeO/bo0kNE9c+/Q8JWmyhSYMwAaglnACudCqNCW2g7lFMUn8p18TrEZsS/wegNXf7MMRmFV5AT8zMR2v2ZGRjJRXFY6hP0Eq4G3TnkQGc7SPp/ayv0qqBQZ3UbHBB74+T9ADUCNvfafbrKsXMKAstXf+AZyuMbc=


@aantron I'd feel more comfortable if the $GITHUB_TOKEN was set up in the repo settings, but we can get this running with this token (it currently only has public_repo access) and change it if we like the way the docs are published.

aantron · 2018-10-09T22:03:14Z

I usually publish docs manually, because we want to leave the version for the last release up until the next release.

If/when odoc supports version switching, we can start publishing the dev docs automatically (and document that, so other projects can do it :) ).

leostera · 2018-10-09T22:21:58Z

Good insight. Published docs from master may not reflect the latest release 👍 — we don't want that, so I'll drop those commits and rebase on master after people have had some time to review their previous comments.

leostera · 2018-10-11T20:39:31Z

Alright, rewritten history without automatic publishing.

@aantron can we split this PR so I focus on getting the rest of the TODO's in another one?

aantron · 2018-10-11T21:06:23Z

Yes, of course. Let me know when this one is ready for review.

leostera · 2018-10-12T06:29:12Z

The last one point I'll make is about publishing the docs with Github Pages.

I'd prefer if we used the simpler mechanism they offer, where the docs site is hosted within the master branch, inside of the docs folder. This allows for:

Cleaner PRs that update both the code and the documentation in one go
Simpler workflow, where at the end of my changes I can run make docs and commit that with "Update docs".

Alternatively we could publish to gh-pages branch, which would mean an update to documentation will have to come in two steps: a PR to master, and a commit to gh-pages.

If we opt for the latter, then we should have a straightforward way of doing so (a-la, make docs-publish).

aantron · 2018-10-12T14:37:32Z

@Ostera Given we are going with republishing the docs only at release time (and for any serious errata), I think we want to avoid 1 and 2. We don't want PRs to master to affect the published docs, we want to discourage contributors from being misled into trying to republish them, and the publishing workflow is only going to be carried out by whoever is doing the release (in the coming release, myself).

I think we just need instructions for how the generated dosc (in a .gitignored directory) can be reviewed locally.

I suggest to leave the generated docs out of master for now, and we will put them in gh-pages later. I can create the Makefile target for that now, or next week during release cleanup.

leostera · 2018-10-12T15:03:16Z

Makes sense. There’s a make docs target already, I’ll drop the commit with the docs and add them to .gitignore when I get home 👍🏼

This removes the old manual_usage and refurbishes the main manual of `odoc` to point to several smaller, more focused ones. It scaffolds manuals for: + System Integrations: where we can explain how it works with `dune`, `bsb`, `esy`, etc. + Internals: where we can dig digger into why are the internal representations the way they are and how they fit together at great length. + Using Odoc: where we can explain in tutorials how to make the best use of the features available for documenting interfaces, writing custom pages, and showcasing what we believe are good docs to get inspired by. + A high-level tutorial of how the generation works. --- It also includes a handy make target that will run in CI.

leostera · 2018-10-12T18:36:23Z

@aantron should be good now 👍

aantron · 2018-10-12T19:22:01Z

I see a .swp file committed, perhaps you should remove it? If it might be a problem in the future, maybe we should .gitignore it.

No idea how this came to be. It's a vim swap file for no file.

leostera · 2018-10-12T20:23:26Z

No idea how that file came to be. It's a swap file from vim, but I can't tie it back to any edited fail. I'll make sure it's ignored globally.

Another small change I couldn't get through (since I already had the folder in place) is that make docs didn't create the folder and thus the copy failed.

aantron · 2018-10-12T20:30:57Z

Makefile

@@ -17,6 +17,7 @@ npm-test :

 .PHONY : docs
 docs :
+	mkdir docs


IIRC this will fail if docs/ already exists, you need mkdir -p docs to avoid that.

I need to stop working late at night. Thanks for catching this 🙌

aantron · 2018-10-12T21:57:43Z

Thanks!

rizo reviewed Sep 26, 2018

View reviewed changes

leostera mentioned this pull request Oct 8, 2018

[meta] Roadmap #210

Closed

13 tasks

aantron force-pushed the master branch from 284eacb to 335b64b Compare October 9, 2018 12:52

leostera commented Oct 9, 2018

View reviewed changes

leostera force-pushed the document-flow branch from 144471a to cda0e95 Compare October 11, 2018 20:28

leostera force-pushed the document-flow branch 2 times, most recently from e590734 to a1856d2 Compare October 11, 2018 22:50

aantron mentioned this pull request Oct 12, 2018

Non-existent documentation? #116

Closed

leostera force-pushed the master branch 2 times, most recently from 68eddf2 to 93ae8e0 Compare October 12, 2018 06:39

leostera force-pushed the document-flow branch from a1856d2 to 7e83426 Compare October 12, 2018 18:36

leostera added 2 commits October 12, 2018 22:20

Remove .swp file

fb49e2f

No idea how this came to be. It's a vim swap file for no file.

Create docs folder on docs target

da9150d

aantron reviewed Oct 12, 2018

View reviewed changes

Don't fail if docs dir already exists

6a0ceda

aantron merged commit 84e1311 into ocaml:master Oct 12, 2018

aantron changed the title ~~Documentation for Odoc~~ Begin new odoc manuals Oct 12, 2018

aantron mentioned this pull request Oct 16, 2018

odoc 1.3.0: OCaml documentation generator ocaml/opam-repository#12811

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Begin new odoc manuals #203

Begin new odoc manuals #203

leostera commented Sep 26, 2018 •

edited

Loading

leostera commented Sep 26, 2018

rizo Sep 26, 2018

pmetzger Sep 26, 2018

leostera Sep 27, 2018

rizo Sep 27, 2018

rizo Sep 26, 2018

pmetzger Sep 26, 2018

rizo Sep 26, 2018

rizo Sep 26, 2018

rizo Sep 26, 2018

rizo Sep 26, 2018

rizo commented Sep 26, 2018

grabbou commented Sep 26, 2018

aantron commented Sep 26, 2018

rizo commented Sep 27, 2018 •

edited

Loading

leostera commented Oct 9, 2018

leostera commented Oct 9, 2018

leostera commented Oct 9, 2018

leostera Oct 9, 2018

aantron commented Oct 9, 2018

leostera commented Oct 9, 2018 •

edited

Loading

leostera commented Oct 11, 2018

aantron commented Oct 11, 2018

leostera commented Oct 12, 2018

aantron commented Oct 12, 2018

leostera commented Oct 12, 2018

leostera commented Oct 12, 2018

aantron commented Oct 12, 2018

leostera commented Oct 12, 2018

aantron Oct 12, 2018

leostera Oct 12, 2018

aantron commented Oct 12, 2018

		@@ -0,0 +1,252 @@
		{1:top odoc}

		The documentation compiler for OCaml, Reason, and BuckleScript.


		{2:overview What is [odoc] really?}

		[odoc] is not your regular documentation tool.

Begin new odoc manuals #203

Begin new odoc manuals #203

Conversation

leostera commented Sep 26, 2018 • edited Loading

TO DO

Follow-up Work

leostera commented Sep 26, 2018

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

rizo commented Sep 26, 2018

grabbou commented Sep 26, 2018

aantron commented Sep 26, 2018

rizo commented Sep 27, 2018 • edited Loading

leostera commented Oct 9, 2018

leostera commented Oct 9, 2018

leostera commented Oct 9, 2018

Choose a reason for hiding this comment

aantron commented Oct 9, 2018

leostera commented Oct 9, 2018 • edited Loading

leostera commented Oct 11, 2018

aantron commented Oct 11, 2018

leostera commented Oct 12, 2018

aantron commented Oct 12, 2018

leostera commented Oct 12, 2018

leostera commented Oct 12, 2018

aantron commented Oct 12, 2018

leostera commented Oct 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aantron commented Oct 12, 2018

leostera commented Sep 26, 2018 •

edited

Loading

rizo commented Sep 27, 2018 •

edited

Loading

leostera commented Oct 9, 2018 •

edited

Loading