On Saturday, 24 February 2018 at 10:13:35 UTC, Paolo Invernizzi wrote:
>>>
>>> Have you tried to generate the documentation?
>>>
>>> Look for example inside the source files...
>>>
>>> https://github.com/pszturmaj/ddb/blob/bd55beea0df6e5da86a71535ff6d9800c0711c7c/source/ddb/postgres.d#L2
>>>
>>> https://github.com/pszturmaj/ddb/blob/bd55beea0df6e5da86a71535ff6d9800c0711c7c/source/ddb/db.d#L19
>>>
>
> I think no...
>
> The documentation on how to use the package is present, it's just inside the modules as Ddoc documentation.
>
> Joe, you can easily 'extract' it using the proper -D compiler switch

As I said, I'm new and still not familiar with those facilities although I saw those things and they looked like embedded HTML and was wondering what they were for.

Again, coming from Python, I'm familiar with RTD (https://readthedocs.org, my own open source Python/Postgres project is hosted there) and Sphinx (http://www.sphinx-doc.org/en/master/). Although it started with Python, RTD now hosts many other kinds of projects (Javascript, PHP, Ruby, etc.). There's even a project named 'dlang' (it's not what you expect!), but I did find "D Tips" and "Quick Start with D" which appear to be standalone Markdown. In any case, it would be nice to have such automatically generated docs available in a public site/repo of some kind, like RTD, so a potential user doesn't have to clone the code and run the compiler to see it.

On Saturday, 24 February 2018 at 14:13:18 UTC, Joe wrote:
> On Saturday, 24 February 2018 at 10:13:35 UTC, Paolo Invernizzi
[...]
>
> As I said, I'm new and still not familiar with those facilities although I saw those things and they looked like embedded HTML and was wondering what they were for.
>
> Again, coming from Python, I'm familiar with RTD (https://readthedocs.org, my own open source Python/Postgres project is hosted there) and Sphinx (http://www.sphinx-doc.org/en/master/). Although it started with Python, RTD now hosts many other kinds of projects (Javascript, PHP, Ruby, etc.). There's even a project named 'dlang' (it's not what you expect!), but I did find "D Tips" and "Quick Start with D" which appear to be standalone Markdown. In any case, it would be nice to have such automatically generated docs available in a public site/repo of some kind, like RTD, so a potential user doesn't have to clone the code and run the compiler to see it.
+1
I would even go so far 'force' people publishing to dub, to provide documentation.
If no docs, present, than the libs should be marked as *docs missing*. (Beside the number of Github stars)

On Saturday, 24 February 2018 at 14:54:21 UTC, Martin Tschierschke wrote:

> I would even go so far 'force' people publishing to dub, to provide documentation.
> If no docs, present, than the libs should be marked as *docs missing*. (Beside the number of Github stars)

If there's no documentation, the project has no business cluttering up the website, and should not be published on Dub.

On Saturday, 24 February 2018 at 14:13:18 UTC, Joe wrote:
> Again, coming from Python, I'm familiar with RTD

So I actually just made this extension to my dpldocs website:

http://ddb.dpldocs.info/ddb.postgres.html


You can try going to

http://any-dub-package.dpldocs.info

and it will try to build the docs on demand.

for example:
http://dpq.dpldocs.info/dpq.html



If you're the first user to hit a page, it might take some time to load and send you to a random page once generation is complete, but then you can navigate with the sidebar to see the rest.


I literally just slapped this together now, so I expect it won't be perfect, but this has been on my todo list for a year (I even bought a VPS to host it on... 6 months ago and have been paying for it without even using it!), so it was time to do.

On Saturday, 24 February 2018 at 15:32:32 UTC, Adam D. Ruppe wrote:
> On Saturday, 24 February 2018 at 14:13:18 UTC, Joe wrote:
>> Again, coming from Python, I'm familiar with RTD
>
> So I actually just made this extension to my dpldocs website:
>
> http://ddb.dpldocs.info/ddb.postgres.html
>
>
> You can try going to
>
> http://any-dub-package.dpldocs.info
>
> and it will try to build the docs on demand.
>
> for example:
> http://dpq.dpldocs.info/dpq.html
>
>
>
> If you're the first user to hit a page, it might take some time to load and send you to a random page once generation is complete, but then you can navigate with the sidebar to see the rest.
>
>
> I literally just slapped this together now, so I expect it won't be perfect, but this has been on my todo list for a year (I even bought a VPS to host it on... 6 months ago and have been paying for it without even using it!), so it was time to do.

:-O

Adam, you are the man!
I'll never stop of being surprised by your way of coding!

Great Job!

Joe: I think this is also a terrific 'welcome aboard' about how fast and quickly things can be done in D!

:-P

/Paolo

On Saturday, 24 February 2018 at 15:44:49 UTC, Paolo Invernizzi wrote:
> On Saturday, 24 February 2018 at 15:32:32 UTC, Adam D. Ruppe wrote:
>> On Saturday, 24 February 2018 at 14:13:18 UTC, Joe wrote:
[...]
>> You can try going to
>>
>> http://any-dub-package.dpldocs.info
[...]
>
> :-O
>
> Adam, you are the man!
> I'll never stop of being surprised by your way of coding!
>
> Great Job!
+1
Fascinating!

Please make a post to announce and place the direct link to it inside code.dlang.org :-)

Would it be possible to use it for calculating/evaluating a measure for inlined documentation?

On Saturday, 24 February 2018 at 15:44:49 UTC, Paolo Invernizzi wrote:
> :-O
>
> Adam, you are the man!

worship me!


So I'm gonna tell you guys a dirty little secret: I intend to take the documentation throne by means of subterfuge. I've been generating docs for popular packages already but it has been a manual process (I, last night, did some hacks to better support gtkd than anyone else I have see: http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html i'm about 80% happy with it.)

The new thing here is just a little program to automate that process when the URL is fetched. But it doesn't do versioning or cross-package referencing or a few of the other things I have planned.... notably, it also ignores the examples/ folders, which are a really useful source (and btw my doc gen web source viewer has go-to-definition omg!)


Still, it is fairly usable as-is and I hope it encourages people to do more dox. And I hope it gets them to use my syntax and features: http://dpldocs.info/experimental-docs/adrdox.syntax.html that i may finally take the crown and rule the D-language area!!!!!!!!11 muahhahah

On Saturday, 24 February 2018 at 16:41:09 UTC, Martin Tschierschke wrote:
> Please make a post to announce and place the direct link to it inside code.dlang.org :-)

Well, I forgot to log errors on the server so I see a few generation failures and I'm not sure if it is because the code is missing docs or if one of my components failed! I'll have to look at the packages in question.

But yeah, I'd like to have the link on code.dlang.org so people can discover it. Let's set a goal of having it ready for that next week.

> Would it be possible to use it for calculating/evaluating a measure for inlined documentation?

Yes, certainly it can tell if it is there or not at least really easily. But if it is not there because it is an internal module and supposed to be not publicly documented or poorly done is harder to tell without some kind of user intervention.

Ideally, of course, I would ascend to godhood and force all packages to explicitly declare internal stuff so it can be automatically analyzed...

On Saturday, 24 February 2018 at 05:33:56 UTC, Joe wrote:
> The main issue is that, other than derelict-pq, using any of these libraries involves reading the library code and understanding the sui generis interfaces implemented by each.

So often in threads like this I chime in to point out my lib too... but ironically, it is poorly documented :P

http://dpldocs.info/experimental-docs/arsd.postgres.PostgreSql.html

Of course, my lib is so thin that there isn't much to document anyway (the source code is ~200 lines)

On Saturday, 24 February 2018 at 16:42:26 UTC, Adam D. Ruppe wrote:
> source viewer

This now works:
http://dpq.dpldocs.info/source/dpq.query.d.html#L29

the "see implementation" links lead to pages like that. You'll notice in the source view that many names are links. You can click on them to go to their definition too. The sidebar has docs links, if applicable.

Note that the main dpldocs.info site has this for Phobos too http://dpldocs.info/experimental-docs/source/std.socket.d.html#L2593 thought I don't update the source often there so it can get out of sync (Phobos is a bit big to rebuild frequently)