Mkdocs, צור תיעוד בזכות תוכנת קוד פתוח זו

במאמר הבא אנו נסתכל על מקדוקס. אם אתה מפתח תוכנה ומחפש פלטפורמה ליצירת תיעוד לאחד מהפרויקטים שלך. או אם אתה עובד בחברה שצריכה ליצור תיעוד פנימי לצוות. גם אם אתה משתמש מתקדם שרוצה לשמור כמה הערות. MkDocs הוא כלי שכדאי לנסות.

תוכנה זו היא מחולל אתרים סטטי שמטרתו ליצור פלטפורמות תיעוד. זה די פשוט, יפה למראה, וקל להתקנה ולפריסה. האם כתוב בפייתון ובפשטות מחייב אותך ליצור את הקבצים שלך בפורמט Markdown. לאחר מכן, באמצעות קובץ תצורה יחיד של YAML, תוכל ליצור אתר סטטי המתאים לך.

בהמשך נראה כמה קל להשיג אתר תיעוד מלא באמצעות MkDocs. ישנם רבים אחרים מחוללי אתרים סטטי דומה, אבל זה יש תצורה ויישום של הפשוטים ביותר.

משתמש רגיל יכול גם להשתמש בתוכנה זו כדי ליצור פלטפורמה מקומית לרישום הערות לעצמו או לכל דבר אחר שדומה לו.

התקן את MkDocs

התקן באופן מקומי

בואו נראה שהתקנת MkDocs היא די קלה. אנו יכולים התקן אותו באמצעות pip. אתה רק צריך לפתוח מסוף (Ctrl + Alt + T) ולכתוב בו:

pip install mkdocs

לאחר ההתקנה, בספריית העבודה שלך, הפעל את הפקודה הבאה ל- לאתחל אתר:

mkdocs new mkdocspro

ואז ל התחל להגיש אותו לָרוּץ:

cd mkdocspro

mkdocs serve

אז את \ ה יכול \ ה עבור אל localhost: 8000 (או את כתובת ה- IP / שם המארח שלך עם יציאה 8000) כדי לראות כיצד MkDocs עובד.

התקן בשרת nginx שלך

מכיוון שמדובר במחולל אתרים סטטי, אין צורך במנוע אחורי כמו PHP או Python. תוכל להטמיע את פרויקט MkDocs בשרת האינטרנט שלך (nginx, apache2) תוך דקה. לדוגמה, הנה ה תצורת מארח וירטואלי של nginx:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

מחליף example.com עם הדומיין שיש לך בשרת שלך. תצטרך גם לשנות / var / www / mkdocspro / site לפי הנתיב של תיקיית המשנה של האתר בשרת שלך. אז יש לנו רק הפעל מחדש את nginx עם הפקודה הבאה:

sudo service nginx restart

עכשיו אתה יכול לעבור אל example.com ולראות את זה עובד.

התקן נושא אחר ב- Mkdocs

ערכת הנושא המוגדרת כברירת מחדל של Mkdocs אינה טובה במיוחד. אבל אתה יכול להתקין עוד אחד תוך דקה. דוגמה להתקנה של נושא אחר תהיה הבאה. איתו אנחנו הולכים להתקין נושא חומר:

pip install mkdocs-material

לאחר ההתקנה, כדי להפעיל את ערכת הנושא, יהיה עליך ערוך את קובץ mkdocs.yml שלך והפוך אותו דומה לזה. ניתן להוסיף כמה אפשרויות:

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

האפשרויות ברורות למדי. אבל הנה כמה הסברים:

• repo_url: האם ה כתובת אתר של מאגר Git. אם אתה מתכנן לשלב את Git ישירות בפרויקט MkDocs שלך, אתה יכול להשתמש באפשרות זו כדי לאפשר לאנשים לערוך את הדפים או להזין את הפרויקט.
• עריכה_אורי: זה פוסט תיקון לעריכת דפים ב- GitHub. אתה יכול לשנות את זה אם אתה משתמש ב- GitLab או GitBucket.
• google_analytics: אין לוח בקרה עבור MkDocs. לכן, לדעת שמבקר באתר שלך, עליך להשתמש בגוגל אנליטיקס. אפשרות זו תאפשר לך להוסיף את מספר המעקב שלך כדי לשייך את חשבונך לאתר.
• Disqus: אם אתה רוצה הפעל את מערכת ההערות של Disqus באתר, תוכל להוסיף את שמך הקצר כאן.
• נושא: The שם העיצוב שבו ברצונך להשתמש. יהיה עליכם להתקין אותו בעבר, כפי שעשינו זה עתה בנושא החומר. זה יהיה השם בו נשתמש בדוגמה.

ראה את השינויים של הנושא החדש

לאחר שמירת הקובץ, הפעל את mkdocs build בתוך התיקיה mkdocsproject. האתר שלך יאמץ את המראה והתחושה המוגדרים כברירת מחדל של נושא החומר:

חשוב: הקפד להריץ תמיד את mkdocs build לאחר כל שינוי שאתה עושה בקבצים. אחרת לא תראה שום שינוי.

יש הרבה נושאים ואפשרויות אחרות להגדרת התצורה של תוכנה זו. אתה יכול להתייעץ איתם ב תיעוד רשמי מאת MkDocs. הנה רשימה של אפשרויות אפשריות שנוכל להשתמש בהם.