हम स्फिंक्स पर एक घंटे में एक पाठ्यपुस्तक या दस्तावेज बनाते हैं

मैं एक वेब प्रोग्रामिंग पाठ्यक्रम सिखा रहा हूं। जब आप लोगों को सिखाते हैं, तो कहावत "जूते के बिना शोमेकर" आप पर लागू नहीं होनी चाहिए: आपको दिखाई देने वाले प्रयास और जल्दी से सब कुछ करना चाहिए। पाठ्यपुस्तक आसान और सरल होनी चाहिए, और अच्छी दिखनी चाहिए।

सामान्य तौर पर, यदि आपको चित्रण के साथ दस्तावेज़ीकरण, एक ट्यूटोरियल, या सिर्फ ग्रंथों का एक सेट बनाने की आवश्यकता है, तो आपको पायथन स्फिंक्स की आवश्यकता है , और यहां मैं आपको बताऊंगा कि कैसे जल्दी से कॉन्फ़िगर करें और इसका उपयोग करें।

पायथन और उपकरण स्थापित करें

विंडोज प्लेटफॉर्म पर, आपको पायथन की आवश्यकता होगी, और मैं इसे आपके होमवर्क के रूप में छोड़ देता हूं। पायथन के अलावा, आपको वितरण पैकेज और कर्ल (या विग) की आवश्यकता है। वितरित और पाइप को डाउनलोड और इंस्टॉल करें:

curl http://python-distribute.org/distribute_setup.py | python curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python 

अब आप स्वयं स्फिंक्स को स्थापित कर सकते हैं:

  pip install sphinx 

* उबंटू / डेबियन में सूडो जोड़ें

एक पाठ्यपुस्तक परियोजना बनाएँ

उसके बाद, बस प्रोजेक्ट के लिए एक फ़ोल्डर बनाएं और उसमें स्फिंक्स-क्विकस्टार्ट स्क्रिप्ट चलाएं। वह कुछ सवाल पूछेगा। इनमें से, मेरी राय में, दो का अलग-अलग उत्तर दिया जाना चाहिए:

  > Separate source and build directories (y/N) [n]: y (        - ) > Create Windows command file? (Y/n) [y]: n (   .bat, - ,    Linux) 

ड्राफ्ट तैयार है। फिर आप index.rst खोल सकते हैं और संपादित करने का प्रयास कर सकते हैं।

ReStructured पाठ का मार्कअप कैसे सीखें? अच्छे सॉफ्टवेयर के लिए रीडिंग डॉक्यूमेंटेशन की आवश्यकता नहीं होती है। स्फिंक्स कोई अपवाद नहीं है: इसके द्वारा बनाए गए सभी पृष्ठों पर, एक लिंक "शो स्रोत" है । किसी और के स्रोतों को देखते हुए, आप बहुत कुछ सीख सकते हैं और जल्दी से। देखो और प्रयोग करो।

कुछ पर्याप्त लिखने के बाद, हम कंसोल में HTML असेंबली शुरू करते हैं:

  make html 

Index.html पेज को _build / html फ़ोल्डर से खोलें, और आनन्दित हों। हमारे पास एक स्थिर खोज साइट तैयार है (जावास्क्रिप्ट में)।

कार विधानसभा

अंत में, जब हमने फाइलों को संपादित करना शुरू किया, तो यह पता चला कि रनिंग html और हर बार ब्राउज़र को अपडेट करना एक बहुत ही थकाऊ काम है। Inotify पैकेज आपको फ़ाइल परिवर्तनों की निगरानी करने और कमांड चलाने की अनुमति देता है। Infotify-tools और xdotool स्थापित करें:

  sudo apt-get install inotify-tools xdotool 

एक स्क्रिप्ट का सबसे सरल संस्करण जो अपडेट को मॉनिटर करता है। वह html और एक फाइल के बहु-पृष्ठ प्रलेखन की असेंबली शुरू करता है, जिसके बाद वह क्रोम में खुले टैब में F5 बटन दबाता है:

  inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move | while read file event; do make singlehtml html xdotool search --name Chromium key --window %@ F5 done 

लेकिन कमियां जल्दी से स्पष्ट हो जाती हैं: कितनी फाइलें अपडेट हुईं, कई बार और विधानसभा शुरू होती है। यह आवश्यक है कि घटनाओं को एक समय में बंद कर दिया जाए। विभिन्न विकल्पों की खोज करने के बाद, मैंने पायथन में अपनी खुद की स्क्रिप्ट नहीं लिखने का फैसला किया, लेकिन एक शेल स्क्रिप्ट के साथ प्राप्त करने के लिए जिसे प्रोजेक्ट फ़ोल्डर से लॉन्च किया गया था:

  inotifywait -mr source --exclude _build -e close_write -e create -e delete -e move --format '%w %e %T' --timefmt '%H%M%S' | while read file event tm; do current=$(date +'%H%M%S') delta=`expr $current - $tm` if [ $delta -lt 2 -a $delta -gt -2 ] ; then sleep 1 #  1         make html singlehtml xdotool search --name Chromium key --window %@ F5 fi done 

वह उस घटना के समय की तुलना उस समय से करता है जब उसकी बारी आती थी। यदि घटना 1-2 सेकंड पहले हुई, तो आपको फिर से दस्तावेज इकट्ठा करने की आवश्यकता है। अन्य प्रणालियों के लिए अपनी नौकरी खत्म करने के लिए (उदाहरण के लिए, एचजी अपडेट समाप्त हो गया है), स्क्रिप्ट 1 सेकंड के लिए सोती है। निर्माण शुरू होता है। उसके बाद, निम्नलिखित घटनाओं को संसाधित किया जाता है, और वे बहुत पुराने हो जाएंगे, इसलिए स्क्रिप्ट उन्हें तुरंत छोड़ देती है।

आप इसे मेकफाइल में भी एम्बेड कर सकते हैं:

  .PHONY autobuild autobuild: <> 

प्रलेखन प्रारूप

स्फिंक्स मल्टी-पेज एचटीएमएल कर सकता है, एक फाइल, साथ ही पीडीएफ, ई-बुक (ईपीयूबी) बना सकता है और किसी ने सीएचएम किया।

पीडीएफ बनाने के 2 तरीके हैं: लेटेक्स स्थापित करें, 1 जीबी पैकेज को पंप करें, लेकिन आउटपुट पर एक कैंडी होगी। एक और विकल्प नया पायथन पैकेज rst2pdf है, जो त्वरित और सरल है, यह एक बहुत ही सरल दिखने वाला पीडीएफ का उत्पादन करेगा। स्टाइल को सभ्य बनाने के लिए उसे कड़ी मेहनत करनी होगी।

पीडीएफ दस्तावेजों को डाउनलोड करना

मैं मुख्य पृष्ठ पर पीडीएफ डाउनलोड करने के लिए एक लिंक जोड़ रहा हूं, यह एक डाउनलोड निर्देश है। ताकि यह पीडीएफ में ही दिखाई न दे, केवल एक ब्लॉक है:

  .. only:: html     :download:`  PDF <../build/latex/manual.pdf>`. 

नोट: जब स्फिंक्स HTML एकत्र करता है, तो वह इस फाइल को स्टैटिक फ़ोल्डर में कॉपी कर देगा। इसलिए, संस्करणों से मिलान करने के लिए, आपको पहले पीडीएफ उत्पन्न करना होगा, उसके बाद ही HTML।

प्रकाशन

3 विकल्प हैं। सबसे सरल है प्रोजेक्ट को BitBucket पर अपलोड करना, रिपॉजिटरी में फ्री रीड द डॉक्स सर्विस को जोड़ना, फिर ReadTheDocs के लिए रजिस्टर करना और वहां एक प्रोजेक्ट बनाना। जब आप मुख्य शाखा में नए संशोधन अपलोड करते हैं, तो आरटीडी उन्हें डाउनलोड करेगा और प्रलेखन को फिर से करेगा। इस प्रकार, प्रोग्राम लाइब्रेरी के लिए प्रलेखन को विशेष रूप से संबोधित करने की आवश्यकता नहीं है: यह डॉकस्ट्रिंग्स को अद्यतित रखने के लिए पर्याप्त है।

यदि आप अपने लिए बंद साइट रखना चाहते हैं, तो आप एक सरल पासवर्ड-संरक्षित साइट बना सकते हैं और इसे मैन्युअल रूप से एकत्र कर सकते हैं। साइट के रूट पर _build / html फ़ोल्डर की सामग्री अपलोड करना पर्याप्त है। मैं इसके लिए rsync का उपयोग करता हूं और Makefile में 2 पंक्तियां लिखता हूं:

 .PHONY: sync sync: latexpdf html rsync -ave ssh build/html/ siberiano@hosting:/home/siberiano/webapps/course_manual/ --delete 

सबसे पहले, दस्तावेज लेटेक्सपीडीएफ प्रारूप में एकत्र किया जाएगा, फिर एचटीएमएल में (और एक पीडीएफ "डाउनलोड" में जोड़ा जाएगा), फिर rsync फाइलों को पुराने (विकल्प --delete) को हटाते हुए होस्टिंग को अपलोड करेगा।

यदि आपको अपने स्वयं के बंद सिस्टम की आवश्यकता है, तो अजनबियों से स्वतंत्र, आप ReadTheDocs क्लोन चला सकते हैं।

सुंदर डिजाइन

स्फिंक्स "विषयों" का उपयोग करता है, ये एक फ़ोल्डर में जिंजा टेम्पलेट और स्थिर फाइलें हैं। मैंने मुफ्त पहुंच से एकत्र किए गए कई विषयों को पोस्ट किया । विषय को सक्षम करने के लिए, आपको conf.py की 2 पंक्तियों को कॉन्फ़िगर करना होगा:

 html_theme = 'armstrong' #   html_theme_path = ['themes'] #   source,     

परिणाम:

सारांश

स्फिंक्स एक बहुत शक्तिशाली उपकरण है जो आपको न्यूनतम डेटा से एक स्थिर वेबसाइट बना सकता है। बहुत सारे स्थिर पाठ और फ़ोटो के लिए, यह सबसे अच्छा विकल्प है। इसे जल्दी से उठाया और बहुत जल्दी अपडेट किया जा सकता है। और सॉफ़्टवेयर पुस्तकालयों के लिए प्रलेखन आम तौर पर आपके प्रयासों के बिना ही इकट्ठा किया जाएगा - बस एक डेवलपर का सपना!

पुनश्च मैं स्वचालित प्रलेखन कैसे करना है के उदाहरण जोड़ना भूल गया। वास्तव में, सेटिंग्स और स्रोत कोड किसी भी परियोजना में देखा जा सकता है, और यह स्फिंक्स-एपिडोक को जानने के लिए भी उपयोगी है।

10/11/12 से परिशिष्ट: GitHub पर, मुझे SublimeText के लिए एक प्रीफ़ॉर्मेट टेबल एडिटर मिला, जो विशेष रूप से उन लोगों के लिए बनाया गया था जो RST और मार्कडाउन को संपादित करते हैं।