diff --git a/.gitignore b/.gitignore index 0c12290..c231e10 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,6 @@ build/ .*project coverage.xml dist/ -docs/_build __pycache__/ .tox .vscode/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5826e4e..b79c5f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1 @@ -Please see [Developer Guidelines](https://docs.plone.org/develop/coredev/docs/guidelines.html) +Please see [Contributing](https://github.com/plone/plone.exportimport/?tab=readme-ov-file#Contributing). diff --git a/MANIFEST.in b/MANIFEST.in index 13c4fa1..a394e0c 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -11,5 +11,3 @@ exclude requirements-mxdev.txt exclude pyvenv.cfg recursive-exclude frontend * recursive-exclude .vscode * -recursive-exclude docs/_build * -graft docs diff --git a/Makefile b/Makefile index 9c312a7..134b876 100644 --- a/Makefile +++ b/Makefile @@ -119,18 +119,3 @@ test: bin/tox ## run tests .PHONY: test-coverage test-coverage: bin/tox ## run tests with coverage bin/tox -e coverage - -# Docs -bin/sphinx-build: bin/pip - bin/pip install -r requirements-docs.txt - -.PHONY: build-docs -build-docs: bin/sphinx-build ## Build the documentation - ./bin/sphinx-build \ - -b html $(DOCS_DIR) "$(DOCS_DIR)/_build/html" - -.PHONY: livehtml -livehtml: bin/sphinx-build ## Rebuild Sphinx documentation on changes, with live-reload in the browser - ./bin/sphinx-autobuild \ - --ignore "*.swp" \ - -b html $(DOCS_DIR) "$(DOCS_DIR)/_build/html" diff --git a/README.md b/README.md index 8911322..0ca0555 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,95 @@ Plone Content Export and Import -Package supporting the export and import of content, principals, relations, and translations from and to a Plone site. +Package supporting the export and import of content, principals, relations, translations, discussions, and redirects from and to a Plone site. ## Introduction This package is a slimmer version of the awesome [collective.exportimport](https://github.com/collective/collective.exportimport). -While `collective.exportimport` supports older Plone versions and Python 2, and also takes care of data conversion -- i.e.: from Archetypes to Dexterity -- this package focus only on latest Plone and Python. +While `collective.exportimport` supports older Plone versions and Python 2, and also takes care of data conversion from Archetypes to Dexterity, this package focuses only on latest Plone and Python. + + +## Documentation + +[`plone.exportimport` documentation](https://6.docs.plone.org/admin-guide/export-import.html) + + + +## Installation + +> [!IMPORTANT] +> This package supports sites running Plone version 6.0 and above. + +> [!IMPORTANT] +> This package is now included with Plone 6.1 and above by default. + +If `plone.exportimport` is not yet available in your Plone installation, add it using `pip`. + +```shell +pip install plone.exportimport +``` + + +## Contributing + +See [Contributing to Plone](https://6.docs.plone.org/contributing/index.html) and [Contribute to Plone 6 core](Contribute to Plone 6 core) for general contributing policies and guidance. + +The following sections specifically describe how to develop and contribute to `plone.exportimport`. + + +### Setup + +You need a working Python environment version 3.8 or later. + +Install the dependencies and a development instance using the following command. + +```shell +make install +``` + + +### Local environment Plone server + +Start Plone, on port 8080, with the following command. + +```shell +make start +``` + + +### Format code base + +Format the code base with the following command. + +```shell +make format +``` + + +### Run tests + +Testing of this package is done with [`pytest`](https://docs.pytest.org/en/stable/) and [`tox`](https://tox.wiki/en/stable/). + +Run all tests with the following command. + +```shell +make test +``` + +Run all tests, but stop on the first error and open a `pdb` session. + +```shell +./bin/tox -e test -- -x --pdb +``` + +Run tests named `TestUtilsDiscussions`. + +```shell +./bin/tox -e test -- -k TestUtilsDiscussions +``` + ## License + The project is licensed under the GPLv2. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 64ff9e4..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,204 +0,0 @@ -# Makefile for Sphinx documentation -.DEFAULT_GOAL = help -SHELL = bash - -# You can set these variables from the command line. -SPHINXOPTS ?= -PAPER ?= - -# Internal variables. -SPHINXBUILD = $(realpath bin/sphinx-build) -SPHINXAUTOBUILD = $(realpath bin/sphinx-autobuild) -DOCS_DIR = ./ -BUILDDIR = ./_build/ -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - - -# Add the following 'help' target to your Makefile -# And add help text after each target name starting with '\#\#' -.PHONY: help -help: # This help message - @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' - -.PHONY: clean -clean: ## Clean docs build directory - cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ - -.PHONY: distclean -distclean: ## Clean docs build directory and Python virtual environment - cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ - rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg - - -bin/python: - python3 -m venv . || virtualenv --clear --python=python3 . - bin/python -m pip install --upgrade pip - bin/pip install -r requirements.txt - -.PHONY: deps -deps: bin/python ## Create Python virtual environment, install requirements. - -.PHONY: html -html: deps ## Build html - cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: manual -manual: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b html -t manual . $(BUILDDIR)/manual - -.PHONY: dirhtml -dirhtml: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: deps - cd $(DOCS_DIR) && $(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: deps - cd $(DOCS_DIR) && $(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/MasteringPlone.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MasteringPlone.qhc" - -.PHONY: devhelp -devhelp: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/MasteringPlone" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MasteringPlone" - @echo "# devhelp" - -.PHONY: epub -epub: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: latex -latex: deps - cd $(DOCS_DIR) && $(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: deps - cd $(DOCS_DIR) && $(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: text -text: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: deps - cd $(DOCS_DIR) && $(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: deps - cd $(DOCS_DIR) && $(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: changes -changes: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: deps ## Run linkcheck - cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/ ." - -.PHONY: linkcheckbroken -linkcheckbroken: deps ## Run linkcheck and show only broken links - cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=auto || test $$? = 1 - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/ ." - -.PHONY: spellcheck -spellcheck: deps ## Run spellcheck - cd $(DOCS_DIR) && LANGUAGE=$* $(SPHINXBUILD) -b spelling -j 4 $(ALLSPHINXOPTS) $(BUILDDIR)/spellcheck/$* - @echo - @echo "Spellcheck is finished; look for any errors in the above output " \ - " or in $(BUILDDIR)/spellcheck/ ." - -.PHONY: html_meta -html_meta: deps ## Add meta data headers to all Markdown pages - python ./docs/addMetaData.py - -.PHONY: doctest -doctest: deps - cd $(DOCS_DIR) && $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: test -test: clean linkcheckbroken spellcheck ## Clean docs build, then run linkcheckbroken, spellcheck - -.PHONY: deploy -deploy: clean html - -.PHONY: livehtml -livehtml: deps ## Rebuild Sphinx documentation on changes, with live-reload in the browser - cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \ - --ignore "*.swp" \ - -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) - -.PHONY: all -all: clean html ## Clean docs build, then run linkcheck and spellcheck, and build html diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico deleted file mode 100644 index ae7bb0c..0000000 Binary files a/docs/_static/favicon.ico and /dev/null differ diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg deleted file mode 100644 index 6bfdc1e..0000000 --- a/docs/_static/logo.svg +++ /dev/null @@ -1,48 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/_static/print.css b/docs/_static/print.css deleted file mode 100644 index 8dbc2d5..0000000 --- a/docs/_static/print.css +++ /dev/null @@ -1,3 +0,0 @@ -.tooltip { - display: none; -} diff --git a/docs/_static/styles.css b/docs/_static/styles.css deleted file mode 100644 index 75d9606..0000000 --- a/docs/_static/styles.css +++ /dev/null @@ -1,465 +0,0 @@ -:root { - /* Add Font Awesome 5 icon and color for todo */ - --pst-icon-clipboard-list: '\f46d'; - --pst-icon-admonition-todo: var(--pst-icon-clipboard-list); - --pst-color-admonition-todo: 161, 46, 233; - --target-color: #b9ee9e; - --codeblock-color: #aad993; -} - -.visuallyhidden { - display: none; -} - -pre { - border-radius: 0; - background-color: white; - box-shadow: none; -} - -a, -a:visited, -main.bd-content #main-content a, -main.bd-content #main-content a:visited { - color: #2980b9; -} - -a:hover, -main.bd-content #main-content a:hover { - color: #1a567e; - text-decoration: none; -} - -ul { - list-style-type: square; -} - -ul li>p { - margin-bottom: 0.3rem; -} - -ol li>p { - margin-bottom: 0.3rem; -} - -img { - margin: 1rem 0; -} - -figure img, -img.figure, -.figure img { - box-shadow: 0 6px 24px 0 rgba(153, 153, 153, 0.3); -} - -.sidebar img.logo { - box-shadow: none; - width: 200px; - margin-bottom: 1rem; -} - -img.inline { - margin: 0; - height: 1em; -} - -span.linenos { - padding-right: 1em; -} - -p.ploneorglink img { - vertical-align: bottom; -} - -dt:target, -span.highlighted, -ul.search li span.highlighted { - background-color: var(--target-color); -} - -.bd-sidebar .nav ul { - padding: 0 0 0 1rem; -} - -.bd-sidebar .nav .toctree-checkbox~label i { - transform: rotate(90deg); -} - -.bd-sidebar .nav .toctree-checkbox:checked~label i { - transform: rotate(0deg); -} - -.toctree-wrapper .caption { - font-weight: bold; - font-size: 1.2em; - margin-top: 3rem; -} - -.toctree-wrapper ul { - list-style: none; -} - -section:not(#glossary) h1~dl { - display: grid; - grid-template-columns: max-content auto; -} - -section:not(#glossary) h1~dl dd { - margin-bottom: unset !important; -} - -div.section { - margin-bottom: 5rem; -} - -div.section div.section { - margin-bottom: 5rem; -} - -div.section div.section div.section { - margin-bottom: 2rem; -} - -/* admonitions */ -.admonition { - border-radius: 0; - border: none; - border-left: .2rem solid; - border-left-color: rgba(var(--pst-color-admonition-default), 1); -} - -.admonition .admonition-title { - margin-bottom: 1.5rem !important; -} - -/* admonition todo */ -.admonition.admonition-todo, -div.admonition.admonition-todo { - border-color: rgba(var(--pst-color-admonition-todo), 1); -} - -.admonition.admonition-todo>.admonition-title, -div.admonition.admonition-todo>.admonition-title { - background-color: rgba(var(--pst-color-admonition-todo), .1); -} - -.admonition.admonition-todo>.admonition-title::before, -div.admonition.admonition-todo>.admonition-title::before { - color: rgba(var(--pst-color-admonition-todo), 1); - content: var(--pst-icon-admonition-todo); -} - -.admonition-github-only.admonition { - display: none; -} - -/* admonition margin */ -.admonition.margin ul, -.admonition.margin ol { - padding-left: 1rem; -} - -.topic { - padding: 1.5em 1em .5em 1em; -} - -.topic-title { - font-weight: bold; -} - - -/* Bootstrap */ -.btn-primary { - color: #fff; - background-color: #2980b9; - border-color: #2980b9; -} - -.btn-primary { - background-color: #1f86ca; - border-color: #2980b9; -} - -/* Search */ - -/* Show search form. It is hidden by default. */ -#search-documentation, -#search-documentation~form, -#search-documentation~p { - display: block; -} - -#search-form:focus-within #shortcut-page, -.bd-search:focus-within #shortcut { - display: none; -} - -#shortcut-page.input-group-text { - padding-top: 0; - padding-bottom: 0; -} - -input#q { - border-radius: .25rem 0 0 .25rem; -} - -.form-control:focus { - box-shadow: none; - border-width: 2px; -} - -ul.search { - margin-left: 0; -} - -p.search-summary { - margin: 1em 0 2rem 0; -} - -#search-results ul { - list-style-type: none; - padding-left: 0; -} - -#search-results ul li, -ul.search li { - margin-bottom: 2rem; - padding: 0; - background-image: none; - border-bottom: none; -} - -#search-results ul li h3 { - margin: 0.4rem 0 .5rem; - font-size: 1.5rem; -} - -#search-results ul li .breadcrumbs { - display: flex; - flex-direction: row; - flex-wrap: wrap; -} - -#search-results ul li .breadcrumbs a { - font-weight: normal; -} - -#search-results ul li .breadcrumbs .lastbreadcrumb { - white-space: nowrap; - display: inline-block; - max-width: 12rem; - overflow: hidden; - /* "overflow"-Wert darf nicht "visible" sein */ - - text-overflow: ellipsis; -} - -ul.search li p.context { - margin-left: 0; -} - -/* Search form sidebar */ - -.bd-search { - font-size: .8rem; -} - -.bd-search:focus-within #search-input { - border-radius: .25rem; -} - -#shortcut.input-group-text { - padding-top: 0; - padding-bottom: 0; -} - -.bd-search input, -.bd-search .input-group-text { - font-size: .8rem; - padding-left: .5em; -} - -input#search-input { - padding-left: 2.1875rem; - border-radius: .25rem 0 0 .25rem; -} - -.search-icon { - position: absolute; - color: #a4a6a7; - left: .625rem; - z-index: 100; - align-self: center; -} - -.input-group-text kbd { - padding: 0rem 0.4rem; - font-size: 135%; -} - -.pathseparator { - padding: 0 0.7rem; -} - -/* header-article */ -div.header-article__label { - display: flex; - align-items: center; - margin: 0 auto 0 1em; - font-size: 80%; - overflow: hidden; - white-space: nowrap; -} - -/* submenu */ -.bd-toc { - box-shadow: 0 .2rem .5rem rgba(0, 0, 0, .05), 0 0 .0625rem rgba(0, 0, 0, .1); -} - -/* extra sidebar */ -div.sidebar:not(.margin) { - width: 40%; - float: right; - clear: right; - margin: .3rem 0 .3rem 0.5em; - padding: 2rem 0 1.5rem 1rem !important; - background-color: rgba(var(--pst-color-admonition-note), .1); - border: none; - border-left: 8px rgba(var(--pst-color-admonition-default), 1) solid; - border-radius: .2rem; - box-shadow: 0 .2rem .5rem rgba(0, 0, 0, .05), 0 0 .0625rem rgba(0, 0, 0, .1); -} - -div.sidebar:not(.margin) .figure { - margin-top: 0; - padding-top: 0; - margin-left: 0; - padding-left: 0; -} - -div.sidebar:not(.margin) img.logo { - margin-top: 0; - margin-bottom: .3rem; -} - -div.sidebar:not(.margin) p { - margin-bottom: 0; -} - -div.sidebar:not(.margin) p.sidebar-title { - display: none; -} - -div.sidebar:not(.margin) div.topic { - padding: .5em 0; - background-color: transparent; - border: none; -} - -div.sidebar:not(.margin) pre { - margin: .5em 0 1.5em 0; -} - -div.sidebar:not(.margin) div[class*="highlight-"] { - margin-right: .5em; -} - -div.sidebar:not(.margin) .admonition { - margin-right: .5em; - background-color: #ffffff; -} - -@media (min-width:768px) { - div.sidebar:not(.margin) { - width: 50%; - margin-left: 1.5em; - margin-right: -28%; - } -} - - -main.bd-content #main-content dl.simple dt { - margin-top: .8em; -} - -main.bd-content #main-content dl.simple dt:nth-of-type(1) { - margin-top: 0; -} - -main.bd-content #main-content dl.simple dd { - margin-top: .8em; -} - -main.bd-content #main-content dl.simple dt+dd { - margin-top: 0; -} - -.prev-next-bottom { - margin: 20px 0 30px 0; -} - -.prev-next-bottom a.left-prev, -.prev-next-bottom a.right-next { - padding: 5px 10px; - border: 1px solid rgba(0, 0, 0, .2); - max-width: 45%; - overflow-x: hidden; - color: rgba(0, 0, 0, .65); - border-radius: 10px; -} - -/* Local navigation */ -li.nav-item.toc-entry { - line-height: 1.25em; - margin-bottom: 0.25em; -} - -span.guilabel, -span.menuselection { - border: none; - background: #e7f2fa; - border-radius: 4px; - padding: 4px 5px; - font-size: 90%; - font-weight: bold; - font-style: italic; - white-space: nowrap; -} - - -/* - * extensions - */ - -/* definitions */ -dl.py.function { - display: block !important; - margin-bottom: 5rem; -} - -dl.py.function>dt { - background-color: var(--codeblock-color); - padding: 4px 5px; -} - -dl.py.function>dt:target { - background-color: var(--target-color); -} - -dl.field-list>dt { - padding-left: 0; -} - -/* code blocks */ -div.viewcode-block:target { - padding: 10px 10px; - background-color: var(--codeblock-color); - border-top: 1px solid var(--codeblock-color); - border-bottom: 1px solid var(--codeblock-color); -} - -/* Fix paragraphs in list items. */ -#main-content ol > li > p:nth-child(n+2), -#main-content ul > li > p:nth-child(n+2) { - margin-top: 1em; -} diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 33bbaea..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,103 +0,0 @@ -from pkg_resources import get_distribution - -import sys - - -project = "plone.exportimport" -copyright = "2024, Plone Foundation" - -# The full version, including alpha/beta/rc tags. -release = get_distribution(project).version -# The short X.Y version. -version = ".".join(release.split(".")[0:2]) - -# The suffix of source filenames. -source_suffix = { - ".md": "markdown", - ".rst": "restructuredtext", -} - -extensions = [ - "myst_parser", - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.coverage", - "sphinx.ext.doctest", - "sphinx.ext.todo", - "sphinx.ext.viewcode", - "sphinx_copybutton", - "sphinx_design", - "sphinxext.opengraph", - "sphinx.ext.graphviz", -] -master_doc = "index" - -# locale_dirs = ['translated/'] -language = "en" - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]) -# This enables PDF generation. -latex_documents = [ - ( - "index", - "ploneapi.tex", - "plone.exportimport Documentation", - "", - "manual", - ) -] - - -class Mock: - def __init__(self, *args, **kwargs): - pass - - def __call__(self, *args, **kwargs): - return Mock() - - @classmethod - def __getattr__(cls, name): - if name in ("__file__", "__path__"): - return "/dev/null" - elif name[0] == name[0].upper(): - mockType = type(name, (), {}) - mockType.__module__ = __name__ - return mockType - else: - return Mock() - - -MOCK_MODULES = ["lxml"] -for mod_name in MOCK_MODULES: - sys.modules[mod_name] = Mock() - - -# -- Options for myST markdown conversion to html ----------------------------- - -# For more information see: -# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html -myst_enable_extensions = [ - "deflist", # You will be able to utilise definition lists - # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists - "colon_fence", # You can also use ::: delimiters to denote code fences,\ - # instead of ```. - "substitution", # plone.restapi \ - # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2 - "html_image", # For inline images. \ - # See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html -] - - -# -- 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 = "sphinx_book_theme" -html_logo = "_static/logo.svg" -html_favicon = "_static/favicon.ico" -html_css_files = ["styles.css", ("print.css", {"media": "print"})] -html_static_path = [ - "_static", # Last path wins. See https://github.com/plone/documentation/pull/1442 -] diff --git a/docs/develop.md b/docs/develop.md deleted file mode 100644 index dbac633..0000000 --- a/docs/develop.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -myst: - html_meta: - "description": "How to develop plone.exportimport" - "property=og:description": "How to develop plone.exportimport" - "property=og:title": "Develop plone.exportimport" - "keywords": "Plone 6, plone.exportimport" ---- - -(develop-label)= - -# Develop this package - -## Setup - -You need a working `python` environment (system, `virtualenv`, `pyenv`, etc) version 3.8 or superior. - -Then install the dependencies and a development instance using: - -```bash -make install -``` - -## Local Environment - -### Plone Server - -Start Plone, on port 8080, with the command: - -```bash -make start -``` - -## Format codebase - -```bash -make format -``` - -## Run tests - -Testing of this package is done with [`pytest`](https://docs.pytest.org/) and [`tox`](https://tox.wiki/). - -Run all tests with: - -```bash -make test -``` - -Run all tests but stop on the first error and open a `pdb` session: - -```bash -./bin/tox -e test -- -x --pdb -``` - -Run tests named `TestUtilsDiscussions`: - -```bash -./bin/tox -e test -- -k TestUtilsDiscussions -``` - -## Documentation - -Build this documentation - -```bash -make docs-build -``` - -### Live version -To have a live version -- with auto-update -- of this documentation, run the command: - -```bash -make docs-live -``` - -And then point your browser at [http://localhost:8000](http://localhost:8000) diff --git a/docs/features.md b/docs/features.md deleted file mode 100644 index 1f624ac..0000000 --- a/docs/features.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -myst: - html_meta: - "description": "Features of plone.exportimport" - "property=og:description": "Features of plone.exportimport" - "property=og:title": "Features" - "keywords": "Plone 6, plone.exportimport" ---- - -(features-label)= - -# Features - -The `plone.exportimport` package provides support to export and import all kinds of data from and to Plone sites using a intermediate json-format. - -Most features use `plone.restapi` to serialize and deserialize data. - -## Supported Data - -* Content (Dexterity content items) - * Ordering - * Local Roles - * Versions - * Default Pages -* Principals (Members and Groups) -* Relations (Relationship between content items) -* Translations (Translation groups) -* Discussions (Content comments) -* Redirects (Redirect information) - -## Exported Data Structure - -Some goals of the new data structure are: - -* Support diff of exported data -* Have blob files near the content item that uses it - -In the top level directory with the exported content, we have the following objects: - -| Name | Description | -| --- | --- | -| `content` | Directory containing content item information exported from the site | -| `discussions.json` | JSON File with discussions (comments) exported from the site | -| `principals.json` | JSON File with members and groups exported from the site | -| `redirects.json` | JSON File with redirect information exported from the site | -| `relations.json` | JSON File with content relations exported from the site | -| `translations.json` | JSON File with translation groups exported from the site | - -### Content Directory structure - -In the `content` directory we have all content items exported from the site. Each content item will have its own sub-directory, named with the UID of the content, including the serialized data and all blob files related to this content. - -One special case is the directory for the `Plone Site` object, that will be named **plone_site_root**. - -| Name | Description | -| --- | --- | -| `content/__metadata__.json` | JSON File with metadata information about the exported content | -| `content/` | Directory with serialization for a content item | -| `content/plone_site_root` | Directory with serialization for the Plone Site Root | - -#### Content Item Directory Structure - -Considering we have a File content item with UID `3e0dd7c4b2714eafa1d6fc6a1493f953` and a PDF file named `plone.pdf` (added in the `file` field), the exported directory will look like: - -| Name | Description | -| --- | --- | -| `content/3e0dd7c4b2714eafa1d6fc6a1493f953/data.json` | JSON File with serialized representation of a content item | -| `content/3e0dd7c4b2714eafa1d6fc6a1493f953/file/plone.pdf` | Blob file stored in the `file` field in the content item | - -## Command Line Utilities - -This package provides two command line utilities: `plone-exporter` and `plone-importer`. - -## `plone-exporter` - -Export content from a Plone site to a directory in the file system. - -Usage: - - - `plone-exporter` [--include-revisions] - -Example: - -```shell -plone-exporter instance/etc/zope.conf Plone /tmp/plone_data/ -``` - -By default, the revisions history (older versions of each content item) are not exported. -If you do want them, add `--include-revisions` on the command line. - -## `plone-importer` - -Import content from a file system directory into an existing Plone site. - -Usage: - - - `plone-importer` - -Example: - -```shell -plone-importer instance/etc/zope.conf Plone /tmp/plone_data/ -``` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index f5860c1..0000000 --- a/docs/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -myst: - html_meta: - "description": "Overview of plone.exportimport" - "property=og:description": "Overview of plone.exportimport" - "property=og:title": "Plone Export/Import Support" - "keywords": "Plone 6, plone.exportimport" ---- -(index-label)= - -# Plone Export/Import Support - -## Overview - -This package is a slimmer version of the awesome [collective.exportimport](https://github.com/collective/collective.exportimport). - -While `collective.exportimport` supports older Plone versions and Python 2, and also takes care of data conversion -- i.e.: from Archetypes to Dexterity -- this package focus only on latest Plone and Python. - - -```{toctree} -:maxdepth: 3 -:hidden: true - -installation -features -develop - -``` diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index bce97c4..0000000 --- a/docs/installation.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -myst: - html_meta: - "description": "Installation of plone.exportimport" - "property=og:description": "Installation of plone.exportimport" - "property=og:title": "Installation" - "keywords": "Plone 6, plone.exportimport" ---- - -(installation-label)= - -# Installation - -**This package supports sites running Plone version 6.0 and above.** - -Add **plone.exportimport** to the Plone installation using `pip`: - -```bash -pip install plone.exportimport -``` - -## Load the package - -To make this package available to a Plone installation, you need to load its ZCML configuration. - -If your project has a Python package with custom code, add the following line to your package's `dependencies.zcml` or `configure.zcml`: - -```xml - -``` - -An alternative to that is to use the `instance.yaml` configuration file provided by [`cookiecutter-zope-instance`](https://github.com/plone/cookiecutter-zope-instance). - -Look for the `zcml_package_includes` configuration and add this package to the list of packages already listed there: - -```yaml - zcml_package_includes: ['my.package', 'plone.exportimport'] -``` diff --git a/news/46.documentation b/news/46.documentation new file mode 100644 index 0000000..efed97b --- /dev/null +++ b/news/46.documentation @@ -0,0 +1 @@ +Migrate documentation to README.md and https://6.docs.plone.org/admin-guide/export-import.html. @stevepiercy diff --git a/requirements-docs.txt b/requirements-docs.txt deleted file mode 100644 index 62029e6..0000000 --- a/requirements-docs.txt +++ /dev/null @@ -1,23 +0,0 @@ -docutils<0.17,>=0.15 # sphinx-book-theme 0.2.0 has requirement docutils<0.17,>=0.15 -Sphinx<5,>=3 # sphinx-book-theme 0.3.3 has requirement sphinx<5,>=3 -graphviz -lesscpy -linkify-it-py -myst-parser -pydata-sphinx-theme==0.8.1 # Build fails in 0.9.0. See https://github.com/plone/documentation/issues/1297 -sphinx-autobuild -sphinx-book-theme==0.3.3 # Temporary pin until we can sort out HTML refactoring. -sphinx-copybutton -sphinx-design # Documentation only -sphinx-notfound-page # Documentation only -sphinx-reredirects -sphinx-sitemap -sphinx-togglebutton -sphinxcontrib-applehelp==1.0.4 # https://github.com/plone/documentation/issues/1604 -sphinxcontrib-devhelp==1.0.2 # https://github.com/plone/documentation/issues/1604 -sphinxcontrib-htmlhelp==2.0.1 # https://github.com/plone/documentation/issues/1604 -sphinxcontrib-qthelp==1.0.3 # https://github.com/plone/documentation/issues/1604 -sphinxcontrib-serializinghtml==1.1.5 # https://github.com/plone/documentation/issues/1604 -sphinxcontrib-video -sphinxext-opengraph -vale==2.30.0