Generating documentation for sub-systems

[Symbolics]

I am trying to generate documentation for a sub-system and declt is having trouble with the directory names. The use case is a plotting system, with multiple back-ends, so there is a system called plot, with functions common to all plots, and plot/vglt for the Vega-Lite back-end. When I try to generate the docs with:

(declt:declt :plot/vglt
         :library-name "Common Lisp Plotting"
         :copyright-years +copyright-years+
         :declt-notice nil
         :hyperlinks t)

I get:

Error opening #P"s:/src/plot/./plot/vglt.texi":
  The system cannot find the path specified.
   [Condition of type SB-INT:SIMPLE-FILE-ERROR]

I tried creating the directory as a workaround but it doesn't fix the problem.

A related issue: how can I specify multiple systems? In this case, I'd like to recursively document plot and all the back-end systems into a single manual.

[Symbolics]

Any ideas?

[didierverna]

Hi,

sorry for the delay. If you can wait a couple more weeks, I have a extensive set of changes pending, which I'm about to push to the trunk, and I prefer to wait for that to happen before addressing this issue.

Currently, I believe that you can use the :texi-name key when calling DECLT to change the name of the Texinfo file, but of course, Declt should notice that you're not documenting a primary system and handle the situation by itself. Beware that this key will disapear in my upcoming changes (it will be replaced with :file-name).

As for documenting multiple systems, Declt currently already incorporates all sub-systems it finds under the same directory as the primary one. If the directories are separate, I suppose I should extend Declt to accept a list of systems instead of a single one as argument. I'll look into it; it shouldn't be too hard.

[Symbolics]

Has it been a couple of weeks yet? :wink:

[Symbolics]

Are these pending changes available on a branch? I'm keen to generate API docs for a few systems.

[snunez1]

I've run into this problem again. Any workarounds?

[didierverna]

The first problem is that your system name contains a slash, and so will the file name (by default). Lisp doesn't have any problem with that, but on Unix, you'll end up have the name "plot/vglt" seen as the name "vglt" within a plot/ directory. You need to provide an alternate file name. I'm not sure this is the job of Declt, because what to replace the slash with could be a matter of personal taste. Also, in your original example, the problem is likely to have gone away in Declt trunk, because the default file name is now the library name (but we're discussing reverting that in the other issue).

For the rest, see my previous message, nothing changed. Declt automatically documents subsystems and it's still not currently possible to manually concatenate multiple systems documentation together (other than subsystems). I'll need to give this more thought.

[snunez1]

Do you have an example? I just tried this with the latest code from HEAD, and the subsystem was not documented. Here's the command:

      (declt:declt plot
           :library-name "Plot"
           :copyright-years +copyright-years+
           :license +license+
           :declt-notice :short
           :introduction introduction
           :conclusion conclusion
           :file-name plot)

The main system, 'plot' was documented, but not the 'plot/vega' subsystem. I search the entire directory structure of 'plot', and there's only the plot.texi file, and it contains no documentation for plot/vega.

[snunez1]

As for documenting multiple systems, Declt currently already incorporates all sub-systems it finds under the same directory as the primary one. If the directories are separate, I suppose I should extend Declt to accept a list of systems instead of a single one as argument. I'll look into it; it shouldn't be too hard.

Is this the problem I'm seeing? plot, the front end system, is in plot/src/plot/, and vega, the backend system, is in plot/src/vega/. I suspect this is a common type of system / directory arrangement.

[didierverna]

Do you have an example? I just tried this with the latest code from HEAD, and the subsystem was not documented.

I've tried running Declt on the Quickref setup's parallel subsystem (fr.epita.lrde.quickref.setup/parallel) and it works as expected. I could try to figure out what's going on but can I access your software somewhere ? BTW, recall that Declt needs to have the system actually loaded for it to work. If for some reason, there's a form of conditional inclusion that's not triggered, Declt won't see your subsystem.

[snunez1]

An older version of the system that's causing a problem is here: https://github.com/Lisp-Stat/plot

It may be a dependency problem. The front end that provides a display is independent of the back-end. There could be multiple back ends to display plots. So, the back-end has a dependency on the front end, but not the other way around.

[didierverna]

OK I've clone the repo, quickload'ed the system in order to get all the dependencies, and called declt on :plot/vglt. This is what I get (it looks ok to me). vglt.pdf

[snunez1]

What command did you use for this? I just tried again after ensuring that plot/vglt was loaded. I can generate documentation for plot, and nothing shows up for plot/vglt. If I try generating documentation specifically for plot/vglt I see:

Component "plot/vglt" not found
   [Condition of type ASDF/FIND-COMPONENT:MISSING-COMPONENT]

Restarts:
 0: [RETRY] Retry ASDF operation.
 1: [CLEAR-CONFIGURATION-AND-RETRY] Retry ASDF operation after resetting the configuration.
 2: [RETRY] Retry SLIME REPL evaluation request.
 3: [*ABORT] Return to SLIME's top level.
 4: [ABORT] abort thread (#<THREAD "repl-thread" RUNNING {1016209E63}>)

Backtrace:
  0: ((LAMBDA NIL :IN ASDF/SYSTEM:FIND-SYSTEM))
  1: (ASDF/SESSION:CONSULT-ASDF-CACHE (ASDF/SYSTEM:FIND-SYSTEM "plot/vglt") #<FUNCTION (LAMBDA NIL :IN ASDF/SYSTEM:FIND-SYSTEM) {10229411DB}>)
  2: (ASDF/SESSION:CALL-WITH-ASDF-SESSION #<FUNCTION (LAMBDA NIL :IN ASDF/SYSTEM:FIND-SYSTEM) {10229411DB}> :OVERRIDE NIL :KEY (ASDF/SYSTEM:FIND-SYSTEM "plot/vglt") :OVERRIDE-CACHE NIL :OVERRIDE-FORCING NI..
  3: ((:METHOD ASDF/SYSTEM:SYSTEM-SOURCE-FILE (SYMBOL)) :PLOT/VGLT) [fast-method]
  4: (ASDF/SYSTEM:SYSTEM-SOURCE-DIRECTORY :PLOT/VGLT)

[snunez1]

OK, it turns out that I have to manually create the directory for this, e.g. plot/docs/plot, I'll see about adjusting this with the :filename argument.