← Back to branch summary

~widelands-dev/widelands-website/django_staticfiles

« back to all changes in this revision

Viewing changes to _ops/create_docs.py

  • Committer: franku
  • Date: 2018-05-07 07:50:32 UTC
  • mto: This revision was merged to the branch mainline in revision 496.
  • Revision ID: somal@arcor.de-20180507075032-a04ywdyq0isvwy6f
Use a specialized conf.py and css for the website, so the widelands-repo isn't modified

Show diffs side-by-side

added added

removed removed

Lines of Context:
_ops/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
import os
 
15
import sys
 
16
import imp
 
17
import shutil
 
18
import glob
 
19
from subprocess import check_call, CalledProcessError
 
20
 
 
21
 
 
22
def get_local_settings():
 
23
    """Get local_settings."""
 
24
 
 
25
    # Didn't find a better way to get the settings from the parent directory
 
26
    try:
 
27
        f, f_path, descr = imp.find_module('../local_settings')
 
28
        settings = imp.load_module('local_settings', f, f_path, descr)
 
29
    except ImportError as why:
 
30
        print("Couldn't find local_settings.py! ", why)
 
31
        sys.exit(1)
 
32
    else:
 
33
        f.close()
 
34
 
 
35
    global SPHINX_DIR, BUILD_DIR
 
36
    SPHINX_DIR = os.path.join(settings.WIDELANDS_SVN_DIR, 'doc/sphinx')
 
37
    BUILD_DIR = os.path.join(settings.MEDIA_ROOT, 'documentation/html_temp')
 
38
 
 
39
    return settings
 
40
 
 
41
 
 
42
def move_docs(settings):
 
43
    """Move the documentation created by sphinxdoc to the correct folder.
 
44
 
 
45
    On unix systems the files were served from the symlink called
 
46
    'html'. On Windows systems the files will only be copied in a folder
 
47
    called 'html'.
 
48
 
 
49
    """
 
50
 
 
51
    if os.name == 'posix':
 
52
        try:
 
53
            # Creating symlinks is only available on unix systems
 
54
            link_name = os.path.join(
 
55
                settings.MEDIA_ROOT, 'documentation/html')
 
56
            target_dir = os.path.join(
 
57
                settings.MEDIA_ROOT, 'documentation/current')
 
58
 
 
59
            if not os.path.exists(target_dir):
 
60
                # only needed on first run
 
61
                os.mkdir(target_dir)
 
62
 
 
63
            if os.path.exists(link_name):
 
64
                # only needed if this script has already run
 
65
                os.remove(link_name)
 
66
 
 
67
            # Temporarily switch the symlink
 
68
            os.symlink(BUILD_DIR, link_name)
 
69
            # Remove current
 
70
            shutil.rmtree(target_dir)
 
71
            # Copy new build to current
 
72
            shutil.copytree(BUILD_DIR, target_dir)
 
73
            # Switch the link to current
 
74
            os.remove(link_name)
 
75
            os.symlink(target_dir, link_name)
 
76
        except:
 
77
            raise
 
78
    else:
 
79
        # Non unix OS: Copy docs
 
80
        try:
 
81
            target_dir = os.path.join(
 
82
                settings.MEDIA_ROOT, 'documentation/html')
 
83
            if os.path.exists(target_dir):
 
84
                shutil.rmtree(target_dir)
 
85
            shutil.copytree(BUILD_DIR, target_dir)
 
86
        except:
 
87
            raise
 
88
 
 
89
    # The newly created directory is no longer needed
 
90
    shutil.rmtree(BUILD_DIR)
 
91
 
 
92
 
 
93
def create_sphinxdoc():
 
94
    """Create the widelands source code documentation.
 
95
 
 
96
    The Documenatation is build by sphinxdoc directly in the directory
 
97
    'settings/MEDIA/documentation/html_temp'.
 
98
 
 
99
    """
 
100
 
 
101
    settings = get_local_settings()
 
102
 
 
103
    if not os.path.exists(SPHINX_DIR):
 
104
        print("Can't find the directory given by WIDELANDS_SVN_DIR in local_settings.py:\n", SPHINX_DIR)
 
105
        sys.exit(1)
 
106
 
 
107
    if os.path.exists(os.path.join(SPHINX_DIR, 'build')):
 
108
 
 
109
        # Clean the autogen* files created by extract_rst.py
 
110
        # This has to be done because sometimes such a file remains after
 
111
        # removing it from extract_rst. sphinx-build throughs an error then.
 
112
        try:
 
113
            for f in glob.glob(os.path.join(SPHINX_DIR, 'source/autogen*')):
 
114
                os.remove(f)
 
115
        except OSError:
 
116
            raise
 
117
 
 
118
    # Locally 'dirhtml' do not work because the staticfiles view disallow
 
119
    # directory indexes, but 'dirhtml' gives nicer addresses in production
 
120
    builder = 'html'
 
121
    if hasattr(settings, 'DEBUG'):
 
122
        # In production local_settings.py has no DEBUG statement
 
123
        builder = 'dirhtml'
 
124
 
 
125
    try:
 
126
        check_call(['python', os.path.join(SPHINX_DIR, 'extract_rst.py')])
 
127
        check_call(['sphinx-build',
 
128
                    '-b', builder,
 
129
                    '-d', os.path.join(SPHINX_DIR, 'build/doctrees'),
 
130
                    '-c', os.path.join(BUILD_DIR, '../../../documentation'),
 
131
                    os.path.join(SPHINX_DIR, 'source'),
 
132
                    os.path.join(BUILD_DIR),
 
133
                    ])
 
134
    except CalledProcessError as why:
 
135
        print('An error occured: {0}'.format(why))
 
136
        sys.exit(1)
 
137
 
 
138
    move_docs(settings)
 
139
 
 
140
if __name__ == '__main__':
 
141
    try:
 
142
        from django.conf import settings
 
143
    except ImportError:
 
144
        print('Are you running this script with activated virtual environment?')
 
145
        sys.exit(1)
 
146
 
 
147
    sys.exit(create_sphinxdoc())