Documenter.jl cumbersome experience

New to Julia
, ,
1

Hi! I’m a new user to Julia that wish to develop some packages. However, when it comes to documentation generation, I find it quite cumbersome.

To be specific, I’m a lazy-ish person, and would try to generate documentations from function docstrings. My problem with Documenter.jl is if it could generate both the README.md and the website in a simple manner?

I know there’s a DocumenterMarkdown.jl package, but then the workflow would be quite complicated, like moving files around, not to mention that the package is sort of unmaintained. To make things even worse, I currently use codeberg, where pages are hosted on a separate branch!

Just here to ask: are there packages to streamline or at least accomplish this without too much hassle? Thanks!

2

Sure it can. You can start from a template like BestieTemplate.jl, which will setup everything you need.

I’m not sure what you are trying to accomplish exactly?

1 Like
3

Sorry I made things unclear! Basically, given docstrings from my functions, I would want to generate both a README.md and the built documenter website. The codeberg part I guess I would have to solve myself by moving the build/ folder into the pages branch, so it might not be too relevant.

Since the DocumenterMarkdown.jl package is not actively maintained, should I still use it or seek for a newer version?

4

Well, the index.md page of the documentation and README.md are usually similar, but not the same. If you update one of them, you often also have to update the other one.

You can do that manually (I use:

meld README.md ./docs/src/index.md

to see the differences and sync them as needed).

Or you ask AI to do that for you.

1 Like
5

That’s good to know! A git-ish tool for diffing I would definitely check it out. I guess in the meantime I will just stick with manually editing stuff. Not too bad since my package is small.

However, I do wonder what creators of larger packages could do about it.

6

I would not do that. The function and type references should not all be in the README.md file. Unless you have a very small package. Usually, in the README.md file I explain the purpose of the package, the installation, and perhaps one example.

And things like license and references.

In the html documentation there would be index.md (similar to README.md), and then a page Types, a page Functions, a page Examples etc.

See for example:

2 Likes
7

Oh yes, I guess that would be the de facto way of doing it, especially for large projects. Even though my package is small, I better stick with that practice. Thanks!