Re: [classlib] VM interface docs ?

["Geir Magnusson Jr." <ge...@pobox.com>]

On Jan 25, 2007, at 11:45 AM, Morozova, Nadezhda wrote:

> Geir,
> I moved the Doxygen-related folders to the drlvm/doxygen folder as you
> suggested. However, I am not sure we should make them part of svn.  
> This
> was the main point in the discussion that we don't track version  
> control
> for all these auto-generated files. Are you now suggesting that we  
> make
> them full members of the site? I think I misunderstood you somehow.

No, I wasn't suggesting that they go into SVN.

What I was saying was that there should be a single empty directory

    subcomponents/drlvm/doxygen

in SVN that the generated content is dropped into.

Right now, that content is dropped into

    subcomponents/drlvm

and I think it's a mess :)


>
> As for getting these files locally, yes, this seems to be a problem. I
> actually left the Regenerating section on the index page empty  
> because I
> am not sure about the right way to do it. We now have the build  
> scripts
> for Doxygen in enhanced/drlvm/trunk/vm/doc folder and they only work
> when located there (dependencies on classlib folders and dir tree
> layout). Now, the site only has a snapshot of these files available  
> from
> the web, and you can't build the Doxygen reference inside the site dir
> tree. So as of now, you must switch to the checked out sources and
> regenerate the reference there, so your site links to reference
> materials won't work locally. Yes, this does not sound very convenient
> and it certainly is not part of website. Your great idea of how to  
> avoid
> this escapes me :(

I don't think I had a great idea for that - only that in the

   subcomponents/drlvm/doxygen

we add a page in SVN that gives the instructions on there the  
material comes from, and set it up so that page is named something  
that gets overwritten when the content is dropped in.

Does that make sense?

geir

>
> Cheers,
> Nadya
>
>
>> -----Original Message-----
>> From: Geir Magnusson Jr. [mailto:geir@pobox.com]
>> Sent: Thursday, January 25, 2007 7:13 PM
>> To: dev@harmony.apache.org
>> Subject: Re: [classlib] VM interface docs ?
>>
>>
>> On Jan 25, 2007, at 10:29 AM, Morozova, Nadezhda wrote:
>>
>>> Hi,
>>> I committed the first site version of the DoxygenStart page for
> DRLVM,
>>> http://harmony.apache.org/subcomponents/drlvm/DoxygenStart.html .
> This
>>> has some intro and defines links to the sources.
>>> I also left some blank space to add instructions for regenerating
>>> locally. I suspect this is what Geir wanted to have when saying:
>>>>> You also might think about creating the "drop into" directory as
>>>>> part of the site, and having a simple page that the *site* creates
>>>>> that sits in that directory, that has information about what is
>>>>> supposed to go there, how a user can generate it, etc.  Have that
>>>>> page be the same name as the "index" page of the generated doxygen
>>>>> stuff.
>>> However, I'm not quite sure I understand what Geir suggests, so I
> left
>>> this mostly blank. Suggestions on what to write on the page are
>>> welcome.
>>
>> What you did is perfectly reasonable.  The only suggestion is that
>> instead of spreading the generated docs in the
>>
>>    subcomponents/drlvm
>>
>> directory, you should put *all* of the generated stuff into a  
>> subdir :
>>
>>    subcomponents/drlvm/doxygen
>>
>> or something.  That makes it *really clear* what's going on.   make
>> that doxygen directory in svn - IOW, make it part of the site you can
>> checkout, and put a small README.txt in it so that when you do check
>> it out, you can grok what it's for.
>>
>> Does that make sense?
>>
>> geir
>>
>>
>>>
>>> Cheers,
>>> Nadya
>>>
>>>
>>>> -----Original Message-----
>>>> From: Geir Magnusson Jr. [mailto:geir@pobox.com]
>>>> Sent: Wednesday, January 24, 2007 7:23 PM
>>>> To: dev@harmony.apache.org
>>>> Subject: Re: [classlib] VM interface docs ?
>>>>
>>>> let me know if you aren't working on this...
>>>>
>>>> On Jan 24, 2007, at 10:06 AM, Geir Magnusson Jr. wrote:
>>>>
>>>>>
>>>>> On Jan 24, 2007, at 8:31 AM, Morozova, Nadezhda wrote:
>>>>>
>>>>>> Hi,
>>>>>> I've got another idea about placing Doxygen docs: have the
>>>>>> generated
>>>>>> docs as we agreed but also have a starting page with links on the
>>>>>> website. We even have this page - see the svn source tree,
>>>>>> trunk/vm/doc/DoxygenStart.html.
>>>>>> Does anybody mind if I add such a page to our website svn?
>>>>>
>>>>> I thought that was the idea - we definitely need to have a page w/
>>>>> links to the right spot on the website where you dump the  
>>>>> generated
>>>>> pages, so that a user can easily find and navigate.  I think  
>>>>> that's
>>>>> perfectly fine. Go for it.
>>>>>
>>>>> You also might think about creating the "drop into" directory as
>>>>> part of the site, and having a simple page that the *site* creates
>>>>> that sits in that directory, that has information about what is
>>>>> supposed to go there, how a user can generate it, etc.  Have that
>>>>> page be the same name as the "index" page of the generated doxygen
>>>>> stuff.
>>>>>
>>>>> that way, when you generate the site yourself, you get a complete
>>>>> site w/ information about where to get and how to create the
>>>>> doxygen content.  Then, when you drop the generated stuff in  
>>>>> place,
>>>>> you just get the right stuff.
>>>>>
>>>>> geir
>>>>>
>>>>>>
>>>>>> Cheers,
>>>>>> Nadya
>>>>>>
>>>>>>
>>>>>>> -----Original Message-----
>>>>>>> From: Geir Magnusson Jr. [mailto:geir@pobox.com]
>>>>>>> Sent: Tuesday, January 23, 2007 10:51 PM
>>>>>>> To: dev@harmony.apache.org
>>>>>>> Subject: Re: [classlib] VM interface docs ?
>>>>>>>
>>>>>>>
>>>>>>> On Jan 23, 2007, at 2:44 PM, Morozova, Nadezhda wrote:
>>>>>>>
>>>>>>>> Geir,
>>>>>>>>> I wasn't thinking dropping them in SVN, but rather just
>>>>>>>>> dropping the
>>>>>>>>> docs into minotaur.
>>>>>>>> I like this approach. I'll regenerate the Doxygen docs for  
>>>>>>>> DRLVM
>>>>>>>> inter-component interfaces and post them there, ok?
>>>>>>>> Do I understand correctly that you sftp to minotaur, put the
>>>>>>>> archive to
>>>>>>>> /www/harmony.apache.org/subcomponents/drlvm|classlib/doxygen  
>>>>>>>> and
>>>>>>>> unzip?
>>>>>>>
>>>>>>> Pretty much. I use scp, and have no clue where it should drop,
> but
>>>>>>> yes :)
>>>>>>>>
>>>>>>>>
>>>>>>>> After the docs are there, We can scan the website for actual  
>>>>>>>> and
>>>>>>>> potential references to classlib and DRLVM Doxygen docs and fix
>>>>>>>> these
>>>>>>>> with new links. What do you say?
>>>>>>>
>>>>>>> yep
>>>>>>>
>>>>>>>>
>>>>>>>> Cheers,
>>>>>>>> Nadya
>>>>>>>>
>>>>>>>>
>>>>>>>>> -----Original Message-----
>>>>>>>>> From: Geir Magnusson Jr. [mailto:geir@pobox.com]
>>>>>>>>> Sent: Tuesday, January 23, 2007 10:37 PM
>>>>>>>>> To: dev@harmony.apache.org
>>>>>>>>> Subject: Re: [classlib] VM interface docs ?
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Jan 23, 2007, at 10:30 AM, Tim Ellison wrote:
>>>>>>>>>
>>>>>>>>>> Geir Magnusson Jr. wrote:
>>>>>>>>>>> On Jan 22, 2007, at 6:33 AM, Tim Ellison wrote:
>>>>>>>>>>>
>>>>>>>>>>>> Yang Paulex wrote:
>>>>>>>>>>>>> For windows, you can download or browse it on my personal
>>> site
>>>>>>>>>>>>> [1]. Or
>>>>>>>>>>>>> you
>>>>>>>>>>>>> can create it by "ant doxygen-natives" and "ant doxygen-
>>>>>>>>>>>>> kernel" at
>>>>>>>>>>>>> <classlib
>>>>>>>>>>>>> working copy>/enhanced/doc directory, supposing you have
>>>>>>>>>>>>> doxygen
>>>>>>>>>>>>> installed.
>>>>>>>>>>>>>
>>>>>>>>>>>>> [1] http://people.apache.org/~pyang/harmonydoc/windows/
>>>>>>>>>>>>
>>>>>>>>>>>> Can we get these linked from, or preferably 'moved to', the
>>>>>>>> website?
>>>>>>>>>>>
>>>>>>>>>>> yes please.  Just manually make a directory
>>>>>>>>>>
>>>>>>>>>> Where are you thinking?  directly in the in the site/docs
> tree?
>>>>>>>>>
>>>>>>>>> I wasn't thinking dropping them in SVN, but rather just
>>>>>>>>> dropping the
>>>>>>>>> docs into minotaur.  It means that in the event of a minotaur
>>>>>>>>> crash
>>>>>>>>> and disk loss, that material would have to be manually
> restored.
>>>>>>>>>
>>>>>>>>> I've done the same thing w/ javadoc in the past on the theory
>>> that
>>>>>> it
>>>>>>>>> was of secondary importance and easy to regenerate.
>>>>>>>>>
>>>>>>>>> geir
>>>>>