From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 74194C433DF for ; Mon, 25 May 2020 12:08:46 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 58C192078B for ; Mon, 25 May 2020 12:08:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2390393AbgEYMIq (ORCPT ); Mon, 25 May 2020 08:08:46 -0400 Received: from mga01.intel.com ([192.55.52.88]:24278 "EHLO mga01.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2390360AbgEYMIp (ORCPT ); Mon, 25 May 2020 08:08:45 -0400 IronPort-SDR: ePG11ChkCwVz0a4Q/EuGkXRcrcjfeJhaUxRlsORb+OMjnm65Ro7+6mPsodFbqK3O8LkFHHwpxj 5wifA/bW39aQ== X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga101.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 25 May 2020 05:08:45 -0700 IronPort-SDR: MygWcGtjGbyUXaoJTsOr9GpDCHGpnY2rFL/1FdxJ9g8Zwa5EZDfo5Ipuaf8l9gATdis2PYPp13 3VDQQyr7PYkA== X-IronPort-AV: E=Sophos;i="5.73,433,1583222400"; d="scan'208";a="441711102" Received: from fliu-mobl1.ger.corp.intel.com (HELO localhost) ([10.249.41.83]) by orsmga005-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 25 May 2020 05:08:43 -0700 From: Jani Nikula To: Konstantin Ryabitsev , Markus Heiser Cc: linux-doc@vger.kernel.org Subject: Re: Building directly with sphinx In-Reply-To: <20200521175122.zcyoa7zz33anokit@chatter.i7.local> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20200520215343.btkr7avo3ruu2iap@chatter.i7.local> <153afc64-542f-3965-0fd3-d1ae93e3a913@darmarit.de> <20200521175122.zcyoa7zz33anokit@chatter.i7.local> Date: Mon, 25 May 2020 15:08:40 +0300 Message-ID: <87367o2p4n.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org On Thu, 21 May 2020, Konstantin Ryabitsev wrote: > On Thu, May 21, 2020 at 10:35:51AM +0200, Markus Heiser wrote: >> > >> > I was playing around with readthedocs.org recently and wanted to see if >> > I could build kernel docs there. I cannot directly run "make htmldocs" >> > there, and it proved to be quite tricky to make sphinx do the right >> > thing without all the things that are being defined in the Makefile. >> > >> > Is it possible at all, or am I wasting my time? >> >> It is wasting time ;) .. The Makefile targets do build intermedaiate >> files using perl and other scripts, this will never work on RTD. > > Okay, I'd suspected as much after poking around things a bit. Another > possibility would be to have a separate repository where we commit the > doc tree (after it's massaged into the "ready to be built with sphinx" > condition). We could run this automatically on our end on each mainline > release, but it's certainly not a necessity. FWIW, when I was developing the Sphinx documentation build for the kernel, I carefully tried to ensure everything would build directly, and consequently also at readthedocs.org. I kept testing it at RTD too. For this reason I kept resisting the addition of any Makefile trickery, and insisting we should do everything through Sphinx. This would have meant writing Sphinx extensions for all the hacks people wanted to add. But it would also have lead to a self-contained system with fewer moving parts, which I thought was worth pursuing. And, obviously, would have made it possible to host the documentation at RTD. I failed. Stuff just keeps piling up in the Makefiles. In fairness, the kernel documentation build was growing too big even for RTD. It kept timing out and/or consuming too much resources. I believe that would have been possible to sort out with the RTD maintainers, given the possibility to host kernel documentation, but there was no point in pursuing this since the docs wouldn't build directly anyway. BR, Jani. >> FWIW: in other projects I worked some time with RTD but at the end >> I gave up: If you have e.g. auto generated content in your build >> process which is not generated by the python developer-mainstream >> tools, RTD gives you too little freedom to implement your more >> or less complex build procedures. And .. often I get the RTD-Oops >> links from search engines .. RTD is (my experience is a while >> ago; "was") not very comfortable to to rebind obsolete URLs to >> new content. >> >> Overall I think kernel.org does a good job .. since years, no need >> for additional RTD confusions; >> >> https://www.kernel.org/doc/html/latest/ > > Glad to hear it. My primary interest in getting it hooked up with RTD > was just from the perspective of creating an external mirror for folks > who are already using RTD. For now, I'm going to shelve this effort and > just continue building docs straight from the tree on our end. > > Thanks for your help! > > -K -- Jani Nikula, Intel Open Source Graphics Center