Re: openLilyLib website

[Urs Liska]

Hi Joram,

thanks for the ffecback.

Am Donnerstag, den 20.02.2020, 23:33 +0100 schrieb Noeck:
> Dear Urs,
> 
> it’s great that you found time for that. It looks nice and I think
> MkDocs is a good choice (would have been my first choice, too).
> 
> While speaking about documentation, I very much like this approach:
> https://www.divio.com/blog/documentation/
> 

I'll definitely have a look, but only after replying ...

> Some nitpicks from me:
> 
> - Should everyone see the "Edit this page" pencils?

Yes. Everybody should be encouraged to join this project ...

>    - Those links are broken for me

... which is of course only possible if the links aren't broken. (
https://github.com/openlilylib-documentation/main-site/issues/1)

> - If you descend into a package documentation, "Home" will not bring
> you
> to openlilylib.org but to the page of the package. While that is
> probably a consequence of your fourth bullet point, I find it
> confusing.

I'm not fully clear how to solve the underlying issue.
In fact "Home" brings you the the home page of the package while "Main
Book" brings you to the top of the whole site. I agree it may be
confusing. The thing is, this site is *not* an actual MkDocs site but a
nested set of MkDocs sites. This brings some additional potential for
more complex set-ups and separation of related sub-books, but it comes
at a cost with complexity.

> - Do you like the brown color?

I haven't given much thought on the colors yet. Each sub-book should
choose its individual color, and the theme has only a limited number of
preconfigured colors (
https://squidfunk.github.io/mkdocs-material/getting-started/#color-palette
). At one point I think we'll want to create a fork of the theme and
add more colors, maybe even with some aesthetic specificity. But that's
nothing that has to be decided at this point. (And I don't dislike that
brown ...).

> 
> >  * Each sub-site is maintained in a separate Git repository and
> >    included as a Git submodule, so it should be straightforward to
> >    manage independent authoring of the documentation by the
> > respective
> >    package maintainers.
> 
> While this theoretically makes sense to separate the packages'
> documentation, I would run from git submodule. But perhaps your use
> case
> is easier than where my experience comes from and you can still
> change
> that decision later in case it makes things easier.

I don't have any significant experience with submodules. But while I
was always a bit worried about them I think this use case is pretty
safe because we're not talking about libraries some code depends on but
essentially they're independent chunks of content. If a submodule is
out of date or whatever simply that part of the site will look bad or
out of date.

> 
> > What I really *want* to have but have no idea so far how to achieve
> > is
> > additional code/API documentation retrieved from the actual source
> > files. There should be a tool to retrieve that from comments (or
> > actual
> > signatures?),
> 
> What do you mean by signatures?

AFAICT there are basically two types of source file documentation
systems: retrieving explicit documentation comments (aka docstrings) or
analyzing the defined classes and functions (i.e. their signatures). Or
a combination where the documentation software analyzes the function
signatures but takes comments for their explanations.

> IMHO, this makes sense for "reference-type" documentation in addition
> to
> other parts of the documentation (cf. link at the top).

As said I'll read up on this, but "reference-type" "in addition" sounds
pretty much exactly like what I have in mind.

Best
Urs

> 
> Cheers,
> Joram
>