From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <ferruh.yigit@intel.com>
Received: from mga01.intel.com (mga01.intel.com [192.55.52.88])
 by dpdk.org (Postfix) with ESMTP id 63C49952
 for <dev@dpdk.org>; Wed,  8 Feb 2017 18:35:53 +0100 (CET)
Received: from fmsmga002.fm.intel.com ([10.253.24.26])
 by fmsmga101.fm.intel.com with ESMTP; 08 Feb 2017 09:35:52 -0800
X-ExtLoop1: 1
X-IronPort-AV: E=Sophos;i="5.35,348,1484035200"; d="scan'208";a="1123863613"
Received: from fyigit-mobl1.ger.corp.intel.com (HELO [10.237.220.137])
 ([10.237.220.137])
 by fmsmga002.fm.intel.com with ESMTP; 08 Feb 2017 09:35:51 -0800
To: Thomas Monjalon <thomas.monjalon@6wind.com>
References: <2081164.5ClB4gsZ3F@xps13>
 <20170127173728.21618-1-ferruh.yigit@intel.com> <1665905.OHHQAK7vyE@xps13>
Cc: John McNamara <john.mcnamara@intel.com>, dev@dpdk.org
From: Ferruh Yigit <ferruh.yigit@intel.com>
Message-ID: <9af1a152-11dc-55e0-b9f4-5e6f54bd3675@intel.com>
Date: Wed, 8 Feb 2017 17:35:51 +0000
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:45.0) Gecko/20100101
 Thunderbird/45.7.1
MIME-Version: 1.0
In-Reply-To: <1665905.OHHQAK7vyE@xps13>
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: 7bit
Subject: Re: [dpdk-dev] [PATCH v2] doc: automate examples file list for API
	doc
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <http://dpdk.org/ml/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Wed, 08 Feb 2017 17:35:53 -0000

On 2/8/2017 12:08 PM, Thomas Monjalon wrote:
> 2017-01-27 17:37, Ferruh Yigit:
>> These files are linked to API documentation as usage samples, list of
>> files created automatically during doc creation.
>>
>> Remove manually updated old one.
>>
>> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> [...]
>> +API_EXAMPLES := $(RTE_OUTPUT)/doc/html/examples.dox
> 
> I feel it should be in $(RTE_OUTPUT)/doc/ because the doc could be generated
> in another format (not HTML only).

Not sure, the rules use this file creates hardcoded
$(RTE_OUTPUT)/doc/html/ folder. Right now only user of this file is html
api document.

Putting this file to the root build/doc folder will work as fine, but I
think that file will look ugly there.

> 
> [...]
> 
>>  	@echo 'doxygen for API...'
>>  	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
>>  	$(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf     && \
>> +	    echo INPUT           += $(API_EXAMPLES)   && \
>>  	    printf 'PROJECT_NUMBER = '                && \
>>  	                      $(MAKE) -rR showversion && \
> 
> It would be nicer to see INPUT here.

OK

> 
>>  	    echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
> 
> [...]
> 
>> +$(API_EXAMPLES):
>> +	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
>> +	@echo "/**" > $(API_EXAMPLES)
>> +	@echo "@page examples DPDK Example Programs" >> $(API_EXAMPLES)
>> +	@echo "" >> $(API_EXAMPLES)
>> +	@find examples -type f -name "*.c" | awk '{ print "@example", $$0 }' >> $(API_EXAMPLES)
> 
> May I suggest this simpler syntax?
> 	find examples -type f -name '*.c' -printf '@example %p\n'

Looks better, thanks.

I will send a new version soon.

> 
> Please prefer simple quotes where possible.
>