From dde46a8d375f89507eec7cfdc782b2a10758bd38 Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 08:46:17 +0200 Subject: [PATCH 01/10] FEATURE: Add documentation rendering Relates: #63 --- .gitlab-ci.yml | 14 +- Documentation/.gitignore | 1 + Documentation/source/conf.py | 293 +++++++++++++++++++++++++++++++++ Documentation/source/index.rst | 22 +++ 4 files changed, 328 insertions(+), 2 deletions(-) create mode 100644 Documentation/.gitignore create mode 100644 Documentation/source/conf.py create mode 100644 Documentation/source/index.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index c4161e6..8b0591d 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,4 +1,4 @@ -image: 'bash:latest' +image: 'bash:latest' before_script: - apk add --no-cache make wget git @@ -9,6 +9,7 @@ before_script: stages: - sync - test + - render sync:github: stage: sync @@ -66,4 +67,13 @@ test:latest: script: - ./vendor/bin/phpunit -# Further stages, and jobs e.g. linting, cgl, etc. +render:documentation: + image: danielsiepmann/sphinx:latest + stage: render + before_script: + - cd Documentation + script: + - make html + artifacts: + paths: + - Documentation/build/html diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000..378eac2 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1 @@ +build diff --git a/Documentation/source/conf.py b/Documentation/source/conf.py new file mode 100644 index 0000000..709fc0e --- /dev/null +++ b/Documentation/source/conf.py @@ -0,0 +1,293 @@ +# -*- coding: utf-8 -*- +# +# Automated TYPO3 Update documentation build configuration file, created by +# sphinx-quickstart on Thu Apr 13 07:58:42 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Automated TYPO3 Update' +copyright = u'2017, Daniel Siepmann' +author = u'Daniel Siepmann' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'0.1.0' +# The full version, including alpha/beta/rc tags. +release = u'0.1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +#html_title = u'Automated TYPO3 Update v0.1.0' + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +#html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'AutomatedTYPO3Updatedoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'AutomatedTYPO3Update.tex', u'Automated TYPO3 Update Documentation', + u'Daniel Siepmann', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'automatedtypo3update', u'Automated TYPO3 Update Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'AutomatedTYPO3Update', u'Automated TYPO3 Update Documentation', + author, 'AutomatedTYPO3Update', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/Documentation/source/index.rst b/Documentation/source/index.rst new file mode 100644 index 0000000..eeb03d1 --- /dev/null +++ b/Documentation/source/index.rst @@ -0,0 +1,22 @@ +.. Automated TYPO3 Update documentation master file, created by + sphinx-quickstart on Thu Apr 13 07:58:42 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Automated TYPO3 Update's documentation! +================================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + From 5c56c1cded0d60d7715f2fde7995d5b8a563c0bc Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 09:04:02 +0200 Subject: [PATCH 02/10] TASK: Add Makefile for documentation rendering --- Documentation/Makefile | 230 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 Documentation/Makefile diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000..4dfa749 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,230 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) + $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/AutomatedTYPO3Update.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/AutomatedTYPO3Update.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/AutomatedTYPO3Update" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/AutomatedTYPO3Update" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." From c388a7e8b3df256bc98609e06c8e4a1071748c83 Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 09:06:34 +0200 Subject: [PATCH 03/10] TASK: Provide _static folder for docs --- Documentation/_static/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 Documentation/_static/.gitkeep diff --git a/Documentation/_static/.gitkeep b/Documentation/_static/.gitkeep new file mode 100644 index 0000000..e69de29 From 8bbc92ba949c206dc384f83cb77315302b0a01d0 Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 09:07:54 +0200 Subject: [PATCH 04/10] BUGFIX: Allow local docs rendering * Update .gitlab-ci.yml to allow running gitlab-runner exec docker render:documentation locally --- .gitlab-ci.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 8b0591d..7e5bbb1 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,5 +1,3 @@ -image: 'bash:latest' - before_script: - apk add --no-cache make wget git - make install-composer @@ -12,6 +10,7 @@ stages: - render sync:github: + image: 'bash:latest' stage: sync before_script: - apk add --no-cache openssh-client git @@ -68,7 +67,7 @@ test:latest: - ./vendor/bin/phpunit render:documentation: - image: danielsiepmann/sphinx:latest + image: 'danielsiepmann/sphinx:latest' stage: render before_script: - cd Documentation From a0e83ebef097aa34fc648a736b714bd5dc3bf1fd Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 09:16:46 +0200 Subject: [PATCH 05/10] TASK: Add checks for documentation * Check for syntax issues. * Check for link integrity. --- .gitlab-ci.yml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7e5bbb1..cd8a2f7 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -66,6 +66,32 @@ test:latest: script: - ./vendor/bin/phpunit +test:documentation:syntax: + image: 'danielsiepmann/sphinx:latest' + stage: test + before_script: + - cd Documentation + script: + - make dummy + artifacts: + when: on_failure + artifacts: + paths: + - Documentation/build/dummy + +test:documentation:external-links: + image: 'danielsiepmann/sphinx:latest' + stage: test + before_script: + - cd Documentation + script: + - make linkcheck + artifacts: + when: on_failure + artifacts: + paths: + - Documentation/build/linkcheck/output.txt + render:documentation: image: 'danielsiepmann/sphinx:latest' stage: render From 8cb68ff6bb4e75301154ca461bd7f39433ade62a Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 10:54:32 +0200 Subject: [PATCH 06/10] TASK: Migrate / write documentation * Add further information and sections, e.g. about contribution and extending. Relates: #63 --- Documentation/source/conf.py | 26 ++++- Documentation/source/configuration.rst | 154 +++++++++++++++++++++++++ Documentation/source/contribution.rst | 36 ++++++ Documentation/source/extending.rst | 94 +++++++++++++++ Documentation/source/features.rst | 110 ++++++++++++++++++ Documentation/source/index.rst | 79 ++++++++++--- Documentation/source/usage.rst | 45 ++++++++ 7 files changed, 525 insertions(+), 19 deletions(-) create mode 100644 Documentation/source/configuration.rst create mode 100644 Documentation/source/contribution.rst create mode 100644 Documentation/source/extending.rst create mode 100644 Documentation/source/features.rst create mode 100644 Documentation/source/usage.rst diff --git a/Documentation/source/conf.py b/Documentation/source/conf.py index 709fc0e..406a886 100644 --- a/Documentation/source/conf.py +++ b/Documentation/source/conf.py @@ -109,9 +109,23 @@ todo_include_todos = True # -- Options for HTML output ---------------------------------------------- +import guzzle_sphinx_theme + +html_theme_path = guzzle_sphinx_theme.html_theme_path() +html_theme = 'guzzle_sphinx_theme' + +# Register the theme as an extension to generate a sitemap.xml +extensions.append("guzzle_sphinx_theme") + +# Guzzle theme options (see theme.conf for more information) +# html_theme_options = { +# # Set the name of the project to appear in the sidebar +# "project_nav_name": project, +# } + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +# html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -123,7 +137,7 @@ html_theme = 'alabaster' # The name for this set of Sphinx documents. # " v documentation" by default. -#html_title = u'Automated TYPO3 Update v0.1.0' +html_title = u'Automated TYPO3 Update v0.1.0' # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -157,7 +171,13 @@ html_static_path = ['_static'] #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': ['logo-text.html', + 'globaltoc.html', + 'localtoc.html', + 'searchbox.html', + ], +} # Additional templates that should be rendered to pages, maps page names to # template names. diff --git a/Documentation/source/configuration.rst b/Documentation/source/configuration.rst new file mode 100644 index 0000000..07023b2 --- /dev/null +++ b/Documentation/source/configuration.rst @@ -0,0 +1,154 @@ +.. _configuration: + +Configuration +============= + +Configuration is done through PHPCS Standards, e.g. provide a custom :file:`ruleset.xml` or inside your +project using a :file:`phpcs.xml.dist`. As this is just a PHPCS-Standard, the official documentation +applies. + +All options available in :file:`ruleset.xml` are also available in your :file:`phpcs.xml` files, as +already documented by phpcs itself. Therefore this documentation will just mention +:file:`ruleset.xml`. + +Beside that, some options are also available through CLI. Examples are always provided. + +The following configuration options are available: + +.. _configuration-legacyExtensions: + +legacyExtensions +---------------- + +Configures which extension names are legacy. Used to provide further checks and warnings about +possible legacy code. All class usages starting with ``Tx_`` where ExtensionName is +defined in this array, will produce a warning, until the class is already found to be deprecaed. + +Can and have to be configured for each sniff, e.g. ``Instanceof`` and ``DocComment``. + +Example: + +.. code:: xml + + + + + + + + +.. _configuration-allowedTags: + +allowedTags +----------- + +Only used inside Sniff ``Typo3Update.LegacyClassnames.DocComment``. + +Configures which tags are checked for legacy class names. + +This way you can add checks for further tags you are using. All strings inside the tag are checked, +so no matter where the class name occurs inside the tag. + +Example: + +.. code:: xml + + + + + + + +.. _configuration-mappingFile: + +mappingFile +----------- + +For auto migrating usages of old class names, a PHP file with a mapping is required. The file has to +be in the composer structure :file:`autoload_classaliasmap.php`. +If TYPO3 is already installed using composer, you can use this file through configuration, or by +copying to the default location, which is :file:`LegacyClassnames.php` in the root of this project. + +Configure where the `LegacyClassnames.php` is located, through ``ruleset.xml`` or using +``--runtime-set``. Default is `LegacyClassnames.php` in the project root. + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Using ``runtime-set``: + +.. code:: bash + + --runtime-set mappingFile /projects/typo3_installation/vendor/composer/autoload_classaliasmap.php + +.. _configuration-vendor: + +vendor +------ + +Used while adding namespaces to legacy class definitions and updating plugin and module +registrations. Default is ``YourCompany`` to enable you to search and replace afterwards. + +If you use multiple vendors through your projects, use the cli to define the vendor and run +``phpcbf`` over specific folders, this way you can update your project step by step with different +vendors. + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Example: + +.. code:: bash + + --runtime-set vendor YourVendor + +.. _configuration-removedFunctionConfigFiles: + +removedFunctionConfigFiles +-------------------------- + +Configure where to look for configuration files defining the removed functions and methods. Default +is ``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver +as much as possible. +Globing is used, so placeholders like ``*`` are possible, see +https://secure.php.net/manual/en/function.glob.php + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Example: + +.. code:: bash + + --runtime-set removedFunctionConfigFiles "/Some/Absolute/Path/*.yaml" + +.. _configuration-removedConstantConfigFiles: + +removedConstantConfigFiles +-------------------------- + +Configure where to look for configuration files defining the removed constants. Default is +``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver as +much as possible. Globing is used, so placeholders like ``*`` are possible, see +https://secure.php.net/manual/en/function.glob.php + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Example: + +.. code:: bash + + --runtime-set removedConstantConfigFiles "/Some/Absolute/Path/*.yaml" diff --git a/Documentation/source/contribution.rst b/Documentation/source/contribution.rst new file mode 100644 index 0000000..7a0ad9d --- /dev/null +++ b/Documentation/source/contribution.rst @@ -0,0 +1,36 @@ +.. _highlight: bash + +Contribution +============ + +The project is hosted at https://git.higidi.com/Automated-TYPO3-Update/automated-typo3-update fill +issues there. Also you can fork and clone the project there and provide merge requests. + +Also you can contact us on `TYPO3 slack`_. + +Documentation +------------- + +Documentation is written using `reStructuredText`_ ans `sphinx`_. + +Just open the files with a text editor and update contents. + +To render documentation locally install `docker`_ and run:: + + docker run -v "$PWD/Documentation":/sphinx danielsiepmann/sphinx + +from within the project root. + +Code +---- + +A :file:`.editorconfig` is already provided to setup your editor. Also `phpcs` is configured, so +make sure to check your coding style with `phpcs`_. + +New sniffs have to be covered by tests, see :ref:`extending-tests`. + +.. _TYPO3 slack: https://typo3.slack.com/messages/@danielsiepmann +.. _docker: https://www.docker.com/ +.. _phpcs: https://github.com/squizlabs/PHP_CodeSniffer +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _sphinx: http://www.sphinx-doc.org/en/stable/ diff --git a/Documentation/source/extending.rst b/Documentation/source/extending.rst new file mode 100644 index 0000000..ad71a8a --- /dev/null +++ b/Documentation/source/extending.rst @@ -0,0 +1,94 @@ +.. _extending: + +Extending +========= + +It's possible to extend the provided migrations. + +Also adding tests is pretty easy and done by adding a folder with an input file and an file +holding the expectations. + +.. _extending-sniffs: + +Sniffs +------ + +Follow the official docs of `phpcs`_: +https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial#creating-the-sniff + +The following resources might be helpful during working with ``phpcs``: + +- https://secure.php.net/manual/en/tokens.php + +- :file:`CodeSniffer/Tokens.php` + +- :file:`CodeSniffer/File.php` + +.. _extending-tests: + +Tests +----- + +We are using `phpunit` as testing framework. + +Adding tests for sniffs is as easy as providing the same folder structure as for the sniff, just +inside the :file:`tests/Fixtures` folder. Instead of adding the sniff as a file, you have to provide +a folder named like the sniff. E.g. you want to add a test for sniff +:file:`src/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff.php`, the following folder +has to exist: :file:`tests/Fixtures/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff/`. + +.. _extending-tests-single: + +Single test per sniff +--------------------- + +Inside of the folder at least a file :file:`InputFileForIssues.php` has to exist, containing PHP +code to use for the test. Also a file :file:`Expected.json` has to exist, with the json result of +calling ``phpcs`` with :file:`InputFileForIssues.php`. + +Everything else is done out of the box. + +If your sniff also implements fixable errors or warnings, you can further provide a +:file:`Expected.diff` which is generated by ``phpcbf``. + +.. _extending-tests-multiple: + +Multiple tests per sniff +------------------------ + +Also it's possible to provide multiple tests for a single sniff, e.g. with different cli arguments +like options for the sniff. In that case you have to place a :file:`Arguments.php` in the folder. +This file returns an array: + +.. code-block:: php + [], + 'customVendor' => [ + 'runtime-set' => [ + 'vendor' => 'MyCustomVendor', + ], + ], + ]; + +In the example above ``defaultVendor`` and ``customVendor` are subfolders containing the same +structure as documented for :ref:`extending-tests-single`. +This way it's possible to run multiple tests per sniff. + +Also you can provide further cli arguments on a key -> value base. Where ``runtime-set`` is special, +as it contains a sub array to provide multiple runtime sets. + +How sniff tests are implemented +------------------------------- + +We just find all folders below :file:`tests/Fixtures/Standards/Typo3Update/Sniffs` ending with +``Sniff`` and check the structure. They are provided to the test itself through a dataprovider in +phpunit. + +We then build the phpcs cli call and execute it against the :file:`InputFileForIssues.php` and +compare the result against the :file:`Expected.json`. Same for :file:`Expected.diff`. The existence +of :file:`Expected.diff` itself will trigger the test for ``phpcbf``. + +.. _phpcs: https://github.com/squizlabs/PHP_CodeSniffer +.. _phpunit: https://phpunit.de/ diff --git a/Documentation/source/features.rst b/Documentation/source/features.rst new file mode 100644 index 0000000..a042484 --- /dev/null +++ b/Documentation/source/features.rst @@ -0,0 +1,110 @@ +.. _features: + +Features +======== + +Migration of old legacy classnames to namespace class names +----------------------------------------------------------- + +Currently we can migrate calls to old legacy class names of the TYPO3 core like ``Tx_Extbase...`` to +new ones like ``\TYPO3\Extbase\...``. This is done for: + +Possible configurations for all sniffs: + +- :ref:`configuration-legacyExtensions` + +Implemented sniffs: + +- PHPDocuments, like Includes and annotations for IDEs. + + Possible extra configurations: + + - :ref:`configuration-allowedTags` + + +- Inheritance like ``extends`` and ``implements``. + +- Static calls like ``t3lib_div::`` to ``\TYPO3\Core\Utility\GeneralUtility``. + +- Static call also checks for ``::class``, as technically we just look before the ``::``. + +- Typehints in methods and function like injects. + +- ``instanceof`` checks. + +- Inline comments for IDEs, e.g. ``/* @var $configurationManager + Tx_Extbase_Configuration_ConfigurationManager */`` + +- Instantiation through ``new``. + +- Instantiation through ``makeInstance``. Only Classnames in Strings are supported, no ``::class``. + +- Instantiation through ``ObjectManager``, check afterwards as this is static and all function calls + using ``get`` and ``create`` will be adjusted. Might be useful to exclude this sniff and run it + separately. + Only Classnames in Strings are supported, no ``::class``. + +- ``use`` statements. + +- ``catch`` of legacy class names. + + +Also definitions of classes, traits and interfaces are migrated too: + +Possible extra configurations: + +- :ref:`configuration-vendor` + + +Definitions are migrated, where namespace is added right after opening php-tag and class name is +replaced with last part. We split by ``_`` as Extbase convention. + +After definitions were migrated, we also migrate the usage in the same way as documented above for +TYPO3 core classes. On first run the definition will be converted, on second run the usage. This is +due to the fact, that PHPCS might find the definition after the usage, so please run twice. + +.. note:: + The configured file will be updated after each run, for each converted class, trait and + interface definition. See :ref:`configuration-mappingFile`. + + +This also covers adding the vendor to plugin and modules in :file:`ext_tables.php` and +:file:`ext_localconf.php`: + +Possible extra configurations: + +- :ref:`configuration-vendor` + + +Add missing vendor to plugin and module registrations and configurations. You might want to set +this to non fixable and warning if you already provide the vendor inside a single Variable, together +with your extension key, as this is not recognized. So the following will be recognized: + + - ``$_EXTKEY,`` + + - ``$VENDOR . $_EXTKEY,`` + + - ``'VENDOR.' . $_EXTKEY,`` + + +While the following will not: + + - ``$key = 'Vendor.' . $_EXTKEY;`` + +Check for removed calls +----------------------- + +Also we check for the following deprecated calls: + +Check for usage of *removed functions* in general. The functions are configured via yaml files. The +location of them is configurable, default is inside the standard itself, and we try to deliver all +information. For configuration options see ``removedFunctionConfigFiles``. + +Check for usage of *removed constants*. The constants are configured in same way as removed +functions. For configuration options see ``removedConstantConfigFiles``. + + +Further checks +-------------- + +- Legacy ajax registrations for TYPO3 Backend. diff --git a/Documentation/source/index.rst b/Documentation/source/index.rst index eeb03d1..93ec3be 100644 --- a/Documentation/source/index.rst +++ b/Documentation/source/index.rst @@ -1,22 +1,69 @@ -.. Automated TYPO3 Update documentation master file, created by - sphinx-quickstart on Thu Apr 13 07:58:42 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. _highlight: bash -Welcome to Automated TYPO3 Update's documentation! -================================================== +About +===== -Contents: +Our goal is to provide automated migrations for TYPO3 updates, as much as possible. + +This should include source code modifications like adjusting old legacy class names to new ones and +providing a list of deprecated calls. + +The official project home page can be found at https://git.higidi.com/Automated-TYPO3-Update/automated-typo3-update . +Please open new issues and merge requests there. You can login with your Github account. + +Github is just used as a mirror for the project. + +Requirements +============ + +To install the project you need ``composer`` to be installed and inside your ``$PATH``. +Otherwise run ``make install-composer`` to install composer. + +Installation +============ + +Run:: + + make install + +Afterwards the :ref:`configuration-mappingFile` is required. + +What does it look like? +======================= + +.. code:: + + $ ./vendor/bin/phpcs -p --colors -s + E + + + FILE: + ---------------------------------------------------------------------- + FOUND 5 ERRORS AFFECTING 5 LINES + ---------------------------------------------------------------------- + 8 | ERROR | [x] Legacy classes are not allowed; found + | | backend_toolbarItem + | | (Typo3Update.LegacyClassnames.Inheritance.legacyClassname) + 14 | ERROR | [x] Legacy classes are not allowed; found TYPO3backend + | | (Typo3Update.LegacyClassnames.DocComment.legacyClassname) + 16 | ERROR | [x] Legacy classes are not allowed; found TYPO3backend + | | (Typo3Update.LegacyClassnames.TypeHint.legacyClassname) + 48 | ERROR | [x] Legacy classes are not allowed; found t3lib_extMgm + | | (Typo3Update.LegacyClassnames.StaticCall.legacyClassname) + 61 | ERROR | [x] Legacy classes are not allowed; found t3lib_div + | | (Typo3Update.LegacyClassnames.StaticCall.legacyClassname) + ---------------------------------------------------------------------- + PHPCBF CAN FIX THE 5 MARKED SNIFF VIOLATIONS AUTOMATICALLY + ---------------------------------------------------------------------- + + Time: 35ms; Memory: 5Mb .. toctree:: :maxdepth: 2 + :hidden: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - + features + configuration + usage + extending + contribution diff --git a/Documentation/source/usage.rst b/Documentation/source/usage.rst new file mode 100644 index 0000000..0159d9c --- /dev/null +++ b/Documentation/source/usage.rst @@ -0,0 +1,45 @@ +.. _highlight: bash + +Usage +===== + +If everything is configured, you can run:: + + ./vendor/bin/phpcbf + +This will run the auto fixer recursive for ```` fixing all issues. + +For some tasks you need to run the above command twice, e.g. for namespace migrations. + +Afterwards you should run:: + + ./vendor/bin/phpcs + +To get information about possible issues that were not autofixed. + +To prevent issues, use the following setup:: + + ./vendor/bin/phpcs --standard=Typo3Update -p --colors --runtime-set mappingFile + +Same for ``phpcbf``. + +Further examples +---------------- + +You might want to add ``-p --colors`` to see that something is happening. + +Also make sure to ignore certain files like libraries or js and css files while running the update. +Check out the official docs for how to do so. + +FAQ +--- + +I do not see any issues regarding TYPO3 update but lots of coding style. + Then you probably have a :file:`phpcs.xml` in your project taking precedence. Add the + ``-standard=`` argument to the call:: + + ./vendor/bin/phpcs --standard=Typo3Update + +I see the error message ``Failed opening required 'Standards/Typo3Update/Sniffs/../../../../LegacyClassnames.php'`` + Then you didn't configure :ref:`configuration-mappingFile`, check the link and update the + configuration. From e05941ea460a5866650dc5651dfea19e096ef5e0 Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 10:55:08 +0200 Subject: [PATCH 07/10] TASK: Add requirements.txt to enable read the docs * As we use a different theme. Relates: #63 --- Documentation/requirements.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation/requirements.txt diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt new file mode 100644 index 0000000..0908555 --- /dev/null +++ b/Documentation/requirements.txt @@ -0,0 +1 @@ +guzzle_sphinx_theme == 0.7 From d15388849efc4d2dee63c6eaf234381880d718b5 Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 10:58:07 +0200 Subject: [PATCH 08/10] TASK: Cleanup gitlab-ci.yml * Remove artifacts which are not necessary as output is shown in job --- .gitlab-ci.yml | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index cd8a2f7..70cce9b 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -73,11 +73,6 @@ test:documentation:syntax: - cd Documentation script: - make dummy - artifacts: - when: on_failure - artifacts: - paths: - - Documentation/build/dummy test:documentation:external-links: image: 'danielsiepmann/sphinx:latest' @@ -86,11 +81,6 @@ test:documentation:external-links: - cd Documentation script: - make linkcheck - artifacts: - when: on_failure - artifacts: - paths: - - Documentation/build/linkcheck/output.txt render:documentation: image: 'danielsiepmann/sphinx:latest' From c87546de29282e4ceabf5f8525f3bb63a321433b Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 11:02:50 +0200 Subject: [PATCH 09/10] BUGFIX: Broken documentation * Fix broken links * Fix broken syntax Relates: #63 --- Documentation/source/contribution.rst | 2 +- Documentation/source/extending.rst | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/source/contribution.rst b/Documentation/source/contribution.rst index 7a0ad9d..a5df793 100644 --- a/Documentation/source/contribution.rst +++ b/Documentation/source/contribution.rst @@ -29,7 +29,7 @@ make sure to check your coding style with `phpcs`_. New sniffs have to be covered by tests, see :ref:`extending-tests`. -.. _TYPO3 slack: https://typo3.slack.com/messages/@danielsiepmann +.. _TYPO3 slack: https://typo3.slack.com/?redir=%2Fmessages%2F%40danielsiepmann .. _docker: https://www.docker.com/ .. _phpcs: https://github.com/squizlabs/PHP_CodeSniffer .. _reStructuredText: http://docutils.sourceforge.net/rst.html diff --git a/Documentation/source/extending.rst b/Documentation/source/extending.rst index ad71a8a..05748bb 100644 --- a/Documentation/source/extending.rst +++ b/Documentation/source/extending.rst @@ -14,7 +14,7 @@ Sniffs ------ Follow the official docs of `phpcs`_: -https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial#creating-the-sniff +https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial#user-content-creating-the-sniff The following resources might be helpful during working with ``phpcs``: @@ -61,6 +61,7 @@ like options for the sniff. In that case you have to place a :file:`Arguments.ph This file returns an array: .. code-block:: php + Date: Thu, 13 Apr 2017 12:04:46 +0200 Subject: [PATCH 10/10] TASK: Add hint how to disable warnings for specific deprecations --- Documentation/source/configuration.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/source/configuration.rst b/Documentation/source/configuration.rst index 07023b2..6209816 100644 --- a/Documentation/source/configuration.rst +++ b/Documentation/source/configuration.rst @@ -13,6 +13,10 @@ already documented by phpcs itself. Therefore this documentation will just menti Beside that, some options are also available through CLI. Examples are always provided. +To disable warnings for specific deprecated parts, e.g. a specific function, you can use the full +sniff name, as we try to add the concrete constant or function name to the sniff. Just run ``phpcs`` +with the ``-s`` option to see sniff names. + The following configuration options are available: .. _configuration-legacyExtensions: