digitalmars.D - help me with dpldocs - how to filter 3rd party libs
- Adam D. Ruppe (23/23) Mar 04 2018 So the dpldocs scraper right now pulls all the .d files out of a
- Norm (11/34) Mar 04 2018 Can you run dub describe and parse the output, which is JSON I
- Adam D. Ruppe (3/8) Mar 04 2018 aye.
- Norm (10/18) Mar 04 2018 Hmm, may have changed, sorry for the bum steer. I should have
- Adam D. Ruppe (15/18) Mar 05 2018 Yeah, in the case I'm looking at now, they aren't listed as dub
- bauss (3/22) Mar 05 2018 Honestly, I'd just open an issue for it and hopefully some
- Guillaume Piolat (7/16) Mar 06 2018 In this case, indeed there is no real need for documentation
So the dpldocs scraper right now pulls all the .d files out of a repo and tries to build docs for them. But in some cases, there's a lot of added dependencies in there that can cause the built to time out. For example, take a look at dlangui: http://dlangui.dpldocs.info/dlangui.html Notice the sidebar on the left has a lot of other packages, including x11 and win32 bindings. Similarly, dplug <http://dplug.dpldocs.info/derelict.html> comes with some derelict things bundled. I'm tempted to say if there's a D package that matches the dub package, just focus on it and leave the others out. I could also read the dub description for excludedSourceFiles or for the ddoxFilterArgs and piggyback off that, though a lot of packages haven't concerned themselves with docs at all and didn't set those either. Really, I think my ideal solution would be to figure out what the library is supposed to export, and focus on that. Its internal implementation details shouldn't matter in docs; who cares if it bundles some dependency when that isn't meant to be part of its public API. But I don't see any way dub reports what this is meant to be, it just eats up all src too. Do you guys have any better ideas?
Mar 04 2018
On Sunday, 4 March 2018 at 22:24:58 UTC, Adam D. Ruppe wrote:So the dpldocs scraper right now pulls all the .d files out of a repo and tries to build docs for them. But in some cases, there's a lot of added dependencies in there that can cause the built to time out. For example, take a look at dlangui: http://dlangui.dpldocs.info/dlangui.html Notice the sidebar on the left has a lot of other packages, including x11 and win32 bindings. Similarly, dplug <http://dplug.dpldocs.info/derelict.html> comes with some derelict things bundled. I'm tempted to say if there's a D package that matches the dub package, just focus on it and leave the others out. I could also read the dub description for excludedSourceFiles or for the ddoxFilterArgs and piggyback off that, though a lot of packages haven't concerned themselves with docs at all and didn't set those either. Really, I think my ideal solution would be to figure out what the library is supposed to export, and focus on that. Its internal implementation details shouldn't matter in docs; who cares if it bundles some dependency when that isn't meant to be part of its public API. But I don't see any way dub reports what this is meant to be, it just eats up all src too. Do you guys have any better ideas?Can you run dub describe and parse the output, which is JSON I think. It used to indicate a role for each source file under each configuration, one of which is "unusedSource". Alternatively you could also take the simple (but fragile) route and dictate a convention. Anything under third-party/thirdparty/third_party/3rdparty/3rd-party/3rd_party will be ignored. Convention based APIs work for the internet CRLF CRLF. Cheers, Norm
Mar 04 2018
On Sunday, 4 March 2018 at 23:18:25 UTC, Norm wrote:Can you run dub describe and parse the output, which is JSON I think. It used to indicate a role for each source file under each configuration, one of which is "unusedSource".I don't see any info like that when I run it here... :(Alternatively you could also take the simple (but fragile) route and dictate a convention.aye.
Mar 04 2018
On Sunday, 4 March 2018 at 23:31:56 UTC, Adam D. Ruppe wrote:On Sunday, 4 March 2018 at 23:18:25 UTC, Norm wrote:Hmm, may have changed, sorry for the bum steer. I should have done this first. Just tried it with a simple test and there is no unusedSource, only "source" roles, but if I have any files in the excludedSourceFiles list they do not appear in the list. Might not help much though, I imagine these third-party sources are built as source only libraries, so they probably appear as source files anyway. Cheers, NormCan you run dub describe and parse the output, which is JSON I think. It used to indicate a role for each source file under each configuration, one of which is "unusedSource".I don't see any info like that when I run it here... :(Alternatively you could also take the simple (but fragile) route and dictate a convention.aye.
Mar 04 2018
On Monday, 5 March 2018 at 01:02:52 UTC, Norm wrote:Might not help much though, I imagine these third-party sources are built as source only libraries, so they probably appear as source files anyway.Yeah, in the case I'm looking at now, they aren't listed as dub packages at all, just files included in the src folder (which btw is how I prefer people to use my libraries too....) I think there is no solid solution for existing things, so I'll have to invent a new config thing. I think I'll do something like included modules for documentation: "something.*" excluded modules for documentation: "something.internal.*" And use that to do processing. Still need to decide on syntax, filename, etc., but it should be doable. By default, I will probably exclude the thirdparty naming conventions and internal (actually it does internal already). I might also have it exclude win32, deimos, arsd, and a few other names I know are commonly used this way, unless specifically overridden.
Mar 05 2018
bauss <jj_1337 live.dk> On Monday, 5 March 2018 at 17:26:21 UTC, Adam D. Ruppe wrote:On Monday, 5 March 2018 at 01:02:52 UTC, Norm wrote:Honestly, I'd just open an issue for it and hopefully some annotation will be added.Might not help much though, I imagine these third-party sources are built as source only libraries, so they probably appear as source files anyway.Yeah, in the case I'm looking at now, they aren't listed as dub packages at all, just files included in the src folder (which btw is how I prefer people to use my libraries too....) I think there is no solid solution for existing things, so I'll have to invent a new config thing. I think I'll do something like included modules for documentation: "something.*" excluded modules for documentation: "something.internal.*" And use that to do processing. Still need to decide on syntax, filename, etc., but it should be doable. By default, I will probably exclude the thirdparty naming conventions and internal (actually it does internal already). I might also have it exclude win32, deimos, arsd, and a few other names I know are commonly used this way, unless specifically overridden.
Mar 05 2018
On Sunday, 4 March 2018 at 22:24:58 UTC, Adam D. Ruppe wrote:Similarly, dplug <http://dplug.dpldocs.info/derelict.html> comes with some derelict things bundled.In this case, indeed there is no real need for documentation those internals, since they are not exposed to the library user. Note that those bindings aren't there for no reason, they are based on a modified derelict that works without runtime (wasn't merged into the main Derelict, after a long discussion).Really, I think my ideal solution would be to figure out what the library is supposed to export, and focus on that. Its internal implementation details shouldn't matter in docs; who cares if it bundles some dependency when that isn't meant to be part of its public API. But I don't see any way dub reports what this is meant to be, it just eats up all src too. Do you guys have any better ideas?Extends dub.json to exclude some packages from documentation?
Mar 06 2018