Mkdocs, δημιουργήστε τεκμηρίωση χάρη σε αυτό το λογισμικό ανοιχτού κώδικα

Στο επόμενο άρθρο θα ρίξουμε μια ματιά στο Mkdocs. Εάν αναπτύξετε λογισμικό και αναζητήσετε μια πλατφόρμα για τη δημιουργία τεκμηρίωσης για ένα από τα έργα σας. Ή εάν εργάζεστε σε μια εταιρεία που χρειάζεται να δημιουργήσει εσωτερική τεκμηρίωση για το προσωπικό. Ακόμα κι αν είστε προχωρημένος χρήστης που θέλει να αποθηκεύσει μερικές σημειώσεις. Το MkDocs είναι ένα εργαλείο που πρέπει να δοκιμάσετε.

Αυτό το λογισμικό είναι μια στατική γεννήτρια τοποθεσιών που στοχεύει στη δημιουργία πλατφορμών τεκμηρίωσης. Είναι πολύ απλό, πολύ όμορφο και εύκολο στη ρύθμιση και την ανάπτυξη. Είναι γραμμένο σε python και απλά απαιτεί να δημιουργήσετε τα αρχεία σας σε μορφή 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

Δεδομένου ότι αυτή είναι μια στατική γεννήτρια ιστότοπου, δεν χρειάζεται μηχανή backend όπως 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 / ιστότοπος από τη διαδρομή του υποφακέλου του ιστότοπου στον διακομιστή σας. Τότε έχουμε μόνο επανεκκινήστε το 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: είναι το URL αποθετηρίου Git. Εάν σκοπεύετε να ενσωματώσετε το Git απευθείας στο έργο σας στο MkDocs, μπορείτε να χρησιμοποιήσετε αυτήν την επιλογή για να επιτρέψετε στα άτομα να επεξεργαστούν τις σελίδες ή να διακλαδώσουν το έργο.
• επεξεργασία_uri: Αυτό είναι το postfix για επεξεργασία σελίδων στο GitHub. Μπορείτε να το αλλάξετε εάν χρησιμοποιείτε το GitLab ή το GitBucket.
• google_analytics: Δεν υπάρχει πίνακας ελέγχου για το MkDocs. Επομένως, να ξέρω που επισκέπτεται τον ιστότοπό σας, πρέπει να χρησιμοποιήσετε το Google Analytics. Αυτή η επιλογή θα σας επιτρέψει να εισαγάγετε τον αριθμό παρακολούθησης για να συσχετίσετε τον λογαριασμό σας με τον ιστότοπο.
• Disqus: Αν θέλεις ενεργοποιήστε το σύστημα σχολιασμού Disqus στον ιστότοπο, μπορείτε να εισαγάγετε το σύντομο όνομά σας εδώ.
• θέμα: Η όνομα του θέματος που θέλετε να χρησιμοποιήσετε. Θα πρέπει να το εγκαταστήσετε προηγουμένως, όπως ακριβώς κάναμε με το θέμα του υλικού. Αυτό θα είναι το όνομα που θα χρησιμοποιήσουμε στο παράδειγμα.

Δείτε τις αλλαγές του νέου θέματος

Μετά την αποθήκευση του αρχείου, εκτελέστε το mkdocs build μέσα στο φάκελο mkdocsproject. Ο ιστότοπός σας θα υιοθετήσει την προεπιλεγμένη εμφάνιση και αίσθηση του θέματος Υλικό:

Σημαντικό: φροντίστε να εκτελείτε πάντα το mkdocs build μετά από κάθε τροποποίηση που κάνετε στα αρχεία. Διαφορετικά δεν θα δείτε καμία αλλαγή.

υπάρχουν πολλοί άλλα θέματα και επιλογές για να ρυθμίσετε αυτό το λογισμικό. Μπορείτε να συμβουλευτείτε τους στο επίσημη τεκμηρίωση από το MkDocs. Εδώ είναι μια λίστα με πιθανές επιλογές που μπορούμε να χρησιμοποιήσουμε.