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 >