* extract documentation from (define ...
@ 2019-09-01 21:45 Jesse Gibbons
2019-09-02 4:20 ` sirgazil via General Guile related discussions
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Jesse Gibbons @ 2019-09-01 21:45 UTC (permalink / raw)
To: guile-user mailing list
I am trying to generate documentation for a project written in guile. I
tried "guild doc-snarf" [0] but apparently it only recognizes
documentation in double-semicolon comments. A lot of the project is
documented in a string like one would document an emacs-lisp function.
Is there a program to extract that kind of documentation?
[0]: http://git.savannah.gnu.org/cgit/guile.git/tree/module/scripts/doc
-snarf.scm
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: extract documentation from (define ...
2019-09-01 21:45 extract documentation from (define Jesse Gibbons
@ 2019-09-02 4:20 ` sirgazil via General Guile related discussions
2019-09-02 5:19 ` Jan Nieuwenhuizen
2019-09-04 20:02 ` Mark H Weaver
2 siblings, 0 replies; 7+ messages in thread
From: sirgazil via General Guile related discussions @ 2019-09-02 4:20 UTC (permalink / raw)
To: Jesse Gibbons; +Cc: guile-user mailing list
---- On Sun, 01 Sep 2019 16:45:23 -0500 Jesse Gibbons <jgibbons2357@gmail.com> wrote ----
I am trying to generate documentation for a project written in guile. I
tried "guild doc-snarf" [0] but apparently it only recognizes
documentation in double-semicolon comments. A lot of the project is
documented in a string like one would document an emacs-lisp function.
Is there a program to extract that kind of documentation?
[0]: http://git.savannah.gnu.org/cgit/guile.git/tree/module/scripts/doc
-snarf.scm
I don't know of any program like that for Guile. I was looking for one myself years ago, but couldn't find anything. However, you can extract procedure documentation strings and other metadata using https://www.gnu.org/software/guile/manual/html_node/Procedure-Properties.html. And if you use texinfo for your documentation, take a look at https://www.gnu.org/software/guile/manual/html_node/Texinfo-Processing.html.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: extract documentation from (define ...
2019-09-01 21:45 extract documentation from (define Jesse Gibbons
2019-09-02 4:20 ` sirgazil via General Guile related discussions
@ 2019-09-02 5:19 ` Jan Nieuwenhuizen
2019-09-02 16:22 ` Vladimir Zhbanov
2019-09-04 20:02 ` Mark H Weaver
2 siblings, 1 reply; 7+ messages in thread
From: Jan Nieuwenhuizen @ 2019-09-02 5:19 UTC (permalink / raw)
To: Jesse Gibbons; +Cc: guile-user mailing list
Jesse Gibbons writes:
> I am trying to generate documentation for a project written in guile. I
> tried "guild doc-snarf" [0] but apparently it only recognizes
> documentation in double-semicolon comments. A lot of the project is
> documented in a string like one would document an emacs-lisp function.
> Is there a program to extract that kind of documentation?
For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
strings using. See the `wip-doc' branch and esp.
https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc
You may want to look at the Makefile.am as well for how it's used.
HTH,
janneke
[0] https://savannah.nongnu.org/projects/emacsy
--
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: extract documentation from (define ...
2019-09-02 5:19 ` Jan Nieuwenhuizen
@ 2019-09-02 16:22 ` Vladimir Zhbanov
2019-09-02 17:50 ` Jan Nieuwenhuizen
0 siblings, 1 reply; 7+ messages in thread
From: Vladimir Zhbanov @ 2019-09-02 16:22 UTC (permalink / raw)
To: guile-user
On Mon, Sep 02, 2019 at 07:19:15AM +0200, Jan Nieuwenhuizen wrote:
> Jesse Gibbons writes:
>
> > I am trying to generate documentation for a project written in guile. I
> > tried "guild doc-snarf" [0] but apparently it only recognizes
> > documentation in double-semicolon comments. A lot of the project is
> > documented in a string like one would document an emacs-lisp function.
> > Is there a program to extract that kind of documentation?
>
> For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
> strings using. See the `wip-doc' branch and esp.
>
> https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc
>
> You may want to look at the Makefile.am as well for how it's used.
Cool, thanks!
The only issue i see is no docstrings found for C code
SCM_DEFINE'd Scheme procedures. Probably there might be some
work-around, too (could the optional args of the
module-stexi-documentation() procedure change something here?).
Anyway, I'm pretty happy to see such functionality in Guile :-)
--
Vladimir
(λ)επτόν EDA — https://github.com/lepton-eda
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: extract documentation from (define ...
2019-09-02 16:22 ` Vladimir Zhbanov
@ 2019-09-02 17:50 ` Jan Nieuwenhuizen
2019-09-02 18:01 ` Vladimir Zhbanov
0 siblings, 1 reply; 7+ messages in thread
From: Jan Nieuwenhuizen @ 2019-09-02 17:50 UTC (permalink / raw)
To: guile-user
Vladimir Zhbanov writes:
>> For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
>> strings using. See the `wip-doc' branch and esp.
>>
>> https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc
>>
>> You may want to look at the Makefile.am as well for how it's used.
>
> Cool, thanks!
>
> The only issue i see is no docstrings found for C code
> SCM_DEFINE'd Scheme procedures.
You'll have to modify SCM_DEFINE, its last argument is the docstring.
For another project, I am doing something like
--8<---------------cut here---------------start------------->8---
#undef SCM_DEFINE
#define SCM_DEFINE(FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING) \
SCM_SNARF_HERE( \
SCM_UNUSED static const char s_ ## FNAME [] = PRIMNAME; \
static SCM FNAME ARGLIST \
) \
SCM_SNARF_INIT( \
scm_c_define_gsubr (s_ ## FNAME, REQ, OPT, VAR, \
(SCM_FUNC_CAST_ARBITRARY_ARGS) FNAME); \
scm_c_set_procedure_properties (PRIMNAME, __FILE__, __LINE__, DOCSTRING);\
) \
SCM_SNARF_DOCS(primitive, FNAME, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING)
void
scm_c_set_procedure_properties (char const* name, char const* file_name, int line, char const* doc_string)
{
SCM proc = scm_variable_ref (scm_c_lookup (name));
scm_set_source_property_x (proc,
scm_from_utf8_string ("documentation"),
scm_from_utf8_string (doc_string));
scm_set_source_property_x (proc,
scm_from_utf8_symbol ("location"),
scm_list_2 (scm_cons (scm_from_utf8_string ("file-name"),
scm_from_utf8_string (file_name)),
scm_cons (scm_from_utf8_string ("line"),
scm_from_int (line))));
}
--8<---------------cut here---------------end--------------->8---
The scm_c_set_procedure_properties could be more standard compliant,
hopefully.
HTH,
janneke
--
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: extract documentation from (define ...
2019-09-02 17:50 ` Jan Nieuwenhuizen
@ 2019-09-02 18:01 ` Vladimir Zhbanov
0 siblings, 0 replies; 7+ messages in thread
From: Vladimir Zhbanov @ 2019-09-02 18:01 UTC (permalink / raw)
To: guile-user
On Mon, Sep 02, 2019 at 07:50:40PM +0200, Jan Nieuwenhuizen wrote:
> Vladimir Zhbanov writes:
>
> >> For Emacsy[0] I have used a guild doc-snarf but am now switching to doc
> >> strings using. See the `wip-doc' branch and esp.
> >>
> >> https://git.savannah.nongnu.org/cgit/emacsy.git/tree/scripts/document-module.scm?h=wip-doc
> >>
> >> You may want to look at the Makefile.am as well for how it's used.
> >
> > Cool, thanks!
> >
> > The only issue i see is no docstrings found for C code
> > SCM_DEFINE'd Scheme procedures.
>
> You'll have to modify SCM_DEFINE, its last argument is the docstring.
> For another project, I am doing something like
>
> --8<---------------cut here---------------start------------->8---
> #undef SCM_DEFINE
> #define SCM_DEFINE(FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING) \
> SCM_SNARF_HERE( \
> SCM_UNUSED static const char s_ ## FNAME [] = PRIMNAME; \
> static SCM FNAME ARGLIST \
> ) \
> SCM_SNARF_INIT( \
> scm_c_define_gsubr (s_ ## FNAME, REQ, OPT, VAR, \
> (SCM_FUNC_CAST_ARBITRARY_ARGS) FNAME); \
> scm_c_set_procedure_properties (PRIMNAME, __FILE__, __LINE__, DOCSTRING);\
> ) \
> SCM_SNARF_DOCS(primitive, FNAME, PRIMNAME, ARGLIST, REQ, OPT, VAR, DOCSTRING)
>
> void
> scm_c_set_procedure_properties (char const* name, char const* file_name, int line, char const* doc_string)
> {
> SCM proc = scm_variable_ref (scm_c_lookup (name));
> scm_set_source_property_x (proc,
> scm_from_utf8_string ("documentation"),
> scm_from_utf8_string (doc_string));
> scm_set_source_property_x (proc,
> scm_from_utf8_symbol ("location"),
> scm_list_2 (scm_cons (scm_from_utf8_string ("file-name"),
> scm_from_utf8_string (file_name)),
> scm_cons (scm_from_utf8_string ("line"),
> scm_from_int (line))));
> }
> --8<---------------cut here---------------end--------------->8---
>
>
> The scm_c_set_procedure_properties could be more standard compliant,
> hopefully.
Thanks! Would be nice if the changes go to the guile code and the
`stexi` functions become even more nice :-)
--
Vladimir
(λ)επτόν EDA — https://github.com/lepton-eda
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: extract documentation from (define ...
2019-09-01 21:45 extract documentation from (define Jesse Gibbons
2019-09-02 4:20 ` sirgazil via General Guile related discussions
2019-09-02 5:19 ` Jan Nieuwenhuizen
@ 2019-09-04 20:02 ` Mark H Weaver
2 siblings, 0 replies; 7+ messages in thread
From: Mark H Weaver @ 2019-09-04 20:02 UTC (permalink / raw)
To: Jesse Gibbons; +Cc: guile-user mailing list
Hi Jesse,
Jesse Gibbons <jgibbons2357@gmail.com> writes:
> I am trying to generate documentation for a project written in guile. I
> tried "guild doc-snarf" [0] but apparently it only recognizes
> documentation in double-semicolon comments. A lot of the project is
> documented in a string like one would document an emacs-lisp function.
> Is there a program to extract that kind of documentation?
>
> [0]: http://git.savannah.gnu.org/cgit/guile.git/tree/module/scripts/doc
> -snarf.scm
I would use 'object-documentation' procedure from (ice-9 documentation),
which is what underlies the ,describe REPL command.
Best,
Mark
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2019-09-04 20:02 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-09-01 21:45 extract documentation from (define Jesse Gibbons
2019-09-02 4:20 ` sirgazil via General Guile related discussions
2019-09-02 5:19 ` Jan Nieuwenhuizen
2019-09-02 16:22 ` Vladimir Zhbanov
2019-09-02 17:50 ` Jan Nieuwenhuizen
2019-09-02 18:01 ` Vladimir Zhbanov
2019-09-04 20:02 ` Mark H Weaver
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).