On 01/06/2016 08:50 AM, Jacob Carlborg wrote:
> druntime already uses wildcards [1], if I read the makefile correctly,
> in some places.

Yes, it recently caused Walter some headache because he had a stray file. I think your git ls-files idea would work a lot better. -- Andrei

On 2016-01-06 17:37, Andrei Alexandrescu wrote:

> The remaining issue is that that makes the makefile assume git is
> installed. Is that reasonable?

I think so at least.

-- 
/Jacob Carlborg

On Wednesday, 6 January 2016 at 16:37:24 UTC, Andrei Alexandrescu wrote:
> The remaining issue is that that makes the makefile assume git is installed. Is that reasonable?

I hate to be the one to say this, but I don't think it is reasonable in the packaged release. In the dev version, absolutely, but the packaged release is not a git repository, but still includes the makefile...

However, let's not let the release compromise the development. The release generation script can run git ls-files itself and do some string replacement in the relevant files.

On 2015-12-28 21:15, Adam D. Ruppe wrote:
> Last week, I posted in the general forum my dream for better D docs.
> Today, about 4 days of work later, I'm about 1/4 of the way there.
>
> Still a long way to go, but I've already come so far.
>
> First, behold my old dpldocs.info site. Yes, it is still up and now it
> ties into my new docs! You can use it to quickly jump to a doc given its
> name:
>
> http://dpldocs.info/

BTW, do you know of Harbored [1] and a fork of it [2]? It's documentation generator for D by Brian that uses libdparse.

[1] https://github.com/economicmodeling/harbored
[2] https://github.com/kiith-sa/harbored-mod

-- 
/Jacob Carlborg

On 01/05/2016 01:34 PM, JohnCK wrote:
> On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu wrote:
>> Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along
>> the lines of what you need? What other sort of documentation would you
>> find useful?
>
> I took a look at that link, and you know what would be (at least for me)
> more useful?
>
> A "Let's write a doc example", for example: Creating a sample function
> and documented it, step by step. I really think that would be many times
> more useful and you see that pattern a lot not only for docs, but
> explain things, currently we saw this in another topic about writing a
> scalable chat using vibe.d!

Thanks, that's a neat idea - will keep in mind! -- Andrei

On Wednesday, 6 January 2016 at 17:10:01 UTC, Jacob Carlborg wrote:
> BTW, do you know of Harbored [1]

Yes, I wrote about it in the TWiD link in the snipped section of the parent post.

In fact, until Monday, my generator actually imported a few modules directly from Harbored to handle things like documented unittests and attributes listing. (I have since refactored it, which happened to remove that dependency. That actually wasn't my goal; it was just a nice side effect of the simplified code. I still use the copy/pasted attributes code from harbored though, and still give Brian Schott huge credit for making my thing possible.)


> and a fork of it [2]?

I did not know about that fork though. Looking at it, it falls in the same category to me though: good, but not great. I want something great.

On Wednesday, 6 January 2016 at 15:41:29 UTC, Adam D. Ruppe wrote:
> I know projects get bugs open when they are used, but ddox is a one-person project and that one person doesn't seem terribly active in it.

I'm another user of ddox and fix things when they annoy me.
I don't have many problems with it though.
It you'd joined we'd already be 3.

> https://github.com/rejectedsoftware/ddox/graphs/contributors

The main reasons why work has stalled is that the future of dpl-docs is unclear. Instead of fixing the remaining issues w/ ddox people have spend a huge amount of time to improve ddoc output, so b/c of this weird course Söhnke stopped working on dpl-docs for now.
The other reason is that the existing tool already does most things you want from a documentation system. The styling sucked so I wrote scod, but most of the remaining issues are minor problems that will eventually be addressed. And even if you don't agree w/ some aspect of it, working on a common documentation engine/library makes more sense than having everyone write it's own, in particular if you're arguing about limited time.

On Wed, Jan 6, 2016 at 10:01 PM, Martin Nowak via Digitalmars-d-announce < digitalmars-d-announce@puremagic.com> wrote:

> On Wednesday, 6 January 2016 at 15:41:29 UTC, Adam D. Ruppe wrote:
>
>> I know projects get bugs open when they are used, but ddox is a one-person project and that one person doesn't seem terribly active in it.
>>
>
> I'm another user of ddox and fix things when they annoy me.
> I don't have many problems with it though.
> It you'd joined we'd already be 3.
>
> https://github.com/rejectedsoftware/ddox/graphs/contributors
>>
>
> The main reasons why work has stalled is that the future of dpl-docs is
> unclear. Instead of fixing the remaining issues w/ ddox people have spend a
> huge amount of time to improve ddoc output, so b/c of this weird course
> Söhnke stopped working on dpl-docs for now.
> The other reason is that the existing tool already does most things you
> want from a documentation system. The styling sucked so I wrote scod, but
> most of the remaining issues are minor problems that will eventually be
> addressed. And even if you don't agree w/ some aspect of it, working on a
> common documentation engine/library makes more sense than having everyone
> write it's own, in particular if you're arguing about limited time.
>

I like our current documentation. The only real barrier to entry for non D devs is the weird symbols names we've used for the standard library. They are good names, but they are "sciency". It would be great if people could "tag" symbols in the current documentation website. That way anyone could put things like "go:Dial" in the tags for Socket's "@safe this(Address connectTo);" and "js:contains" in the tags for canFind(). All the symbols in std.algorithm.setops could use some less "sciency" tags.

If not a tagging system then at least adding synonyms would be great.

The documentation on Google Developers is excellent for api discovery, our docs are quite similar I think. (In our company even sales and lead gen use the Google Developers docs to check if something is possible.

I wonder; would it be possible to make the website inline editable and then it automatically creates github pull requests that update the docs in github as D comments?

On Thu, Jan 7, 2016 at 8:30 AM, Rory McGuire <rjmcguire@gmail.com> wrote:

>
>
> On Wed, Jan 6, 2016 at 10:01 PM, Martin Nowak via Digitalmars-d-announce < digitalmars-d-announce@puremagic.com> wrote:
>
>> On Wednesday, 6 January 2016 at 15:41:29 UTC, Adam D. Ruppe wrote:
>>
>>> I know projects get bugs open when they are used, but ddox is a one-person project and that one person doesn't seem terribly active in it.
>>>
>>
>> I'm another user of ddox and fix things when they annoy me.
>> I don't have many problems with it though.
>> It you'd joined we'd already be 3.
>>
>> https://github.com/rejectedsoftware/ddox/graphs/contributors
>>>
>>
>> The main reasons why work has stalled is that the future of dpl-docs is
>> unclear. Instead of fixing the remaining issues w/ ddox people have spend a
>> huge amount of time to improve ddoc output, so b/c of this weird course
>> Söhnke stopped working on dpl-docs for now.
>> The other reason is that the existing tool already does most things you
>> want from a documentation system. The styling sucked so I wrote scod, but
>> most of the remaining issues are minor problems that will eventually be
>> addressed. And even if you don't agree w/ some aspect of it, working on a
>> common documentation engine/library makes more sense than having everyone
>> write it's own, in particular if you're arguing about limited time.
>>
>
> I like our current documentation. The only real barrier to entry for non D devs is the weird symbols names we've used for the standard library. They are good names, but they are "sciency". It would be great if people could "tag" symbols in the current documentation website. That way anyone could put things like "go:Dial" in the tags for Socket's "@safe this(Address connectTo);" and "js:contains" in the tags for canFind(). All the symbols in std.algorithm.setops could use some less "sciency" tags.
>
> If not a tagging system then at least adding synonyms would be great.
>
> The documentation on Google Developers is excellent for api discovery, our docs are quite similar I think. (In our company even sales and lead gen use the Google Developers docs to check if something is possible.
>
>

On Thursday, 7 January 2016 at 07:14:01 UTC, Rory McGuire wrote:
> I wonder; would it be possible to make the website inline editable and then it automatically creates github pull requests that update the docs in github as D comments?

That is a cool idea.

The hard part is backtracking elements in the html so you know what line of code generated that markup. You could infer it from surrounding elements but that will be hairy and brittle. Better to have ddoc emit file and line numbers in the html (as comments or ids or data-attributes, etc.).

Also you would need to know on what commit to base the changes on.