← Back to branch summary

~widelands-dev/widelands-website/trunk

« back to all changes in this revision

Viewing changes to documentation/management/commands/create_docs.py

  • Committer: franku
  • Date: 2019-04-09 06:34:51 UTC
  • mfrom: (530.1.5 mv_main_files)
  • Revision ID: somal@arcor.de-20190409063451-orglu7d2oda37ej9
moved files stored in folder widelands to folder widelands/mainpage

Show diffs side-by-side

added added

removed removed

Lines of Context:
documentation/management/commands/create_docs.py
 
1
#!/usr/bin/env python
 
2
# -*- coding: utf-8 -*-
 
3
 
 
4
"""Create the source code documenation.
 
5
 
 
6
This script covers all needed steps to create or recreate the widelands
 
7
source code documentation.
 
8
 
 
9
Needed dependency: Sphinx
 
10
 
 
11
"""
 
12
 
 
13
from __future__ import print_function
 
14
from django.core.management.base import BaseCommand, CommandError
 
15
from django.conf import settings
 
16
from subprocess import check_call, CalledProcessError
 
17
from documentation import conf
 
18
import os
 
19
import sys
 
20
import shutil
 
21
import glob
 
22
 
 
23
 
 
24
class Command(BaseCommand):
 
25
    help = 'Create the source code documenation.'
 
26
 
 
27
    def __init__(self, *args, **kwargs):
 
28
        super(Command, self).__init__(*args, **kwargs)
 
29
 
 
30
        # Define the main directories used in this class
 
31
        self.sphinx_dir = os.path.join(
 
32
            settings.WIDELANDS_SVN_DIR, 'doc/sphinx')
 
33
        self.build_dir = os.path.join(
 
34
            settings.MEDIA_ROOT, 'documentation/html_temp')
 
35
        self.sphinx_conf_dir = os.path.dirname(conf.__file__)
 
36
 
 
37
    def move_docs(self):
 
38
        """Move the documentation created by sphinxdoc to the correct folder.
 
39
 
 
40
        On unix systems the files were served from the symlink called
 
41
        'html'. On Windows systems the files will only be copied in a
 
42
        folder called 'html'.
 
43
 
 
44
        """
 
45
 
 
46
        if os.name == 'posix':
 
47
            # Creating symlinks is only available on unix systems
 
48
            try:
 
49
                link_name = os.path.join(
 
50
                    settings.MEDIA_ROOT, 'documentation/html')
 
51
                target_dir = os.path.join(
 
52
                    settings.MEDIA_ROOT, 'documentation/current')
 
53
 
 
54
                if not os.path.exists(target_dir):
 
55
                    # only needed on first run
 
56
                    os.mkdir(target_dir)
 
57
 
 
58
                if os.path.exists(link_name):
 
59
                    # only needed if this script has already run
 
60
                    os.remove(link_name)
 
61
 
 
62
                # Temporarily switch the symlink
 
63
                os.symlink(self.build_dir, link_name)
 
64
                # Remove current
 
65
                shutil.rmtree(target_dir)
 
66
                # Copy new build to current
 
67
                shutil.copytree(self.build_dir, target_dir)
 
68
                # Switch the link to current
 
69
                os.remove(link_name)
 
70
                os.symlink(target_dir, link_name)
 
71
            except:
 
72
                raise
 
73
        else:
 
74
            # Non unix OS: Copy docs
 
75
            try:
 
76
                target_dir = os.path.join(
 
77
                    settings.MEDIA_ROOT, 'documentation/html')
 
78
                if os.path.exists(target_dir):
 
79
                    shutil.rmtree(target_dir)
 
80
                shutil.copytree(self.build_dir, target_dir)
 
81
            except:
 
82
                raise
 
83
 
 
84
        try:
 
85
            # The new build directory is no longer needed
 
86
            shutil.rmtree(self.build_dir)
 
87
        except:
 
88
            raise
 
89
 
 
90
    def handle(self, *args, **options):
 
91
        """Create the widelands source code documentation.
 
92
 
 
93
        The Documenatation is built by sphinxdoc in the directory
 
94
        'settings/MEDIA/documentation/html_temp'.
 
95
 
 
96
        """
 
97
 
 
98
        if not os.path.exists(self.sphinx_dir):
 
99
            print(
 
100
                "Can't find the directory given by WIDELANDS_SVN_DIR in local_settings.py:\n", self.sphinx_dir)
 
101
            sys.exit(1)
 
102
 
 
103
        if os.path.exists(os.path.join(self.sphinx_dir, 'build')):
 
104
            # Clean the autogen* files created by extract_rst.py
 
105
            # This has to be done because sometimes such a file remains after
 
106
            # removing it from extract_rst.
 
107
            try:
 
108
                for f in glob.glob(os.path.join(self.sphinx_dir, 'source/autogen*')):
 
109
                    os.remove(f)
 
110
            except OSError:
 
111
                raise
 
112
 
 
113
        # Locally 'dirhtml' do not work because the staticfiles view disallow
 
114
        # directory indexes, but 'dirhtml' gives nicer addresses in production
 
115
        builder = 'html'
 
116
        if not settings.DEBUG:
 
117
            # In production DEBUG is False
 
118
            builder = 'dirhtml'
 
119
 
 
120
        try:
 
121
            check_call(['python', os.path.join(
 
122
                self.sphinx_dir, 'extract_rst.py')])
 
123
            check_call(['sphinx-build',
 
124
                        '-b', builder,
 
125
                        '-d', os.path.join(self.sphinx_dir, 'build/doctrees'),
 
126
                        '-c', self.sphinx_conf_dir,
 
127
                        os.path.join(self.sphinx_dir, 'source'),
 
128
                        self.build_dir,
 
129
                        ])
 
130
        except CalledProcessError as why:
 
131
            print('An error occured: {0}'.format(why))
 
132
            sys.exit(1)
 
133
 
 
134
        self.move_docs()