Merge pull request #16 from alicevision/develop

Time to release best we have for 2019 release and focus on 2020?
alicevision · May 30, 2020 · 9af0eac · 9af0eac
2 parents 5fabe95 + e6b137b
commit 9af0eac
Show file tree

Hide file tree

Showing 68 changed files with 1,347 additions and 276 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,19 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: requirements.txt
diff --git a/.travis.yml b/.travis.yml
@@ -6,7 +6,7 @@ python:
   - 3.5
 
 install:
-  - pip install sphinx
+  - pip install -r requirements.txt
   - source ./ci/texlive/texlive_install.sh
 
 cache:
@@ -20,7 +20,9 @@ script:
   - make latex
   - cd build/latex
   - LATEXNAME=meshroom
-  - pdflatex -interaction nonstopmode -halt-on-error -file-line-error  ${LATEXNAME}.tex
+  #- pdflatex -interaction nonstopmode -halt-on-error -file-line-error  ${LATEXNAME}.tex
+  - pdflatex -interaction nonstopmode -file-line-error  ${LATEXNAME}.tex
+
 
   # in case there are other latex packages to install texliveonfly will do the
   # installation of the required packages automatically
@@ -55,4 +57,4 @@ deploy:
    - ${ARCHIVE_BASE_PATH}/${INSTALL_PDF_FILENAME}
   skip_cleanup: true
   on:
-    tags: true
+    tags: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,3 +3,26 @@
 - make yourself familiar with ReStructuredText and Sphinx
 - do not make any changes to the general structure (yet)
 - open an Issue for questions
+
+# Common conventions
+
+- write one sentence per line of your editor.
+  This helps versioning the code and checking the differences.
+
+- for sections here are the markers and the order of nesting
+
+  ```rst
+
+  First
+  =====
+
+  Second
+  ~~~~~~
+
+  Third
+  +++++
+
+  Fourth
+  ------
+
+  ```
diff --git a/README.md b/README.md
@@ -1,23 +1,18 @@
 [![CC BY-SA 4.0](https://img.shields.io/badge/license-CC%20BY--SA%204.0-blue.svg?style=flat-square)](https://creativecommons.org/licenses/by-sa/4.0/)
 [![language: ReStructuredText](https://img.shields.io/badge/language-RST-black.svg?style=flat-square)](http://docutils.sourceforge.net/docs/user/rst/quickref.html)
 ![HitCount](http://hits.dwyl.io/natowi/meshroom_doc.svg)
-[![all releases](https://img.shields.io/github/downloads/natowi/meshroom_doc/total.svg?style=flat-square&color=success)](https://github.com/natowi/meshroom_doc/releases/)
-![pre-release](https://img.shields.io/github/release-pre/natowi/meshroom_doc.svg?style=flat-square&color=yellow&label=pre-release)
-![release](https://img.shields.io/github/release/natowi/meshroom_doc.svg?style=flat-square&color=green&label=release)
-[![Travis](https://img.shields.io/travis/natowi/meshroom_doc.svg?style=flat-square)](https://travis-ci.org/natowi/meshroom_doc)
+[![all releases](https://img.shields.io/github/downloads/natowi/meshroom_doc/total.svg?style=flat-square&color=success)](https://readthedocs.org/projects/meshroom-manual/downloads/)
+![Read the Docs](https://img.shields.io/readthedocs/meshroom-manual.svg?style=flat-square&color=success)
 
 # About
 
+Read the latest version on https://meshroom-manual.readthedocs.io/en/latest/ 
+download the PDF from https://readthedocs.org/projects/meshroom-manual/downloads/
+
 **This is documentation is work in progress.**
 
 See [Project ToDo](https://github.com/alicevision/meshroom-manual/projects) for details.
 
-# Next update
-+ capturing images for photogrammetry chapters
-+ MR2019.2 updates
-+ improved layout
-+ readthedocs release (including pdf)
-
 # How to contribute
 
 -   make yourself familiar with ReStructuredText and Sphinx
@@ -26,16 +21,22 @@ See [Project ToDo](https://github.com/alicevision/meshroom-manual/projects) for
 
 We could use some help with:
 - optimizing the formatting for pdf&html
+- checking grammar and spelling, fixing typos
 - anything listed here https://github.com/alicevision/meshroom-manual/projects
 
-# How to build on windows
+# How to Build
+
+- install Python 3
+- install a latex package
+- install pip and the rtd theme
+```bash 
+pip install -r requirements.txt
+```
 
--   (install pip)
--   **pip install sphinx**
--   in your cli, navigate to the meshroom\_doc directory
--   type **make html** (this will re-/build the html doc)
+-   in your cli, navigate to the `meshroom-manual` directory
+-   type `make html` (this will re-/build the html doc)
 
-For other build methods read the sphinx documentation
+For other build methods read the sphinx documentation.
 
 # FAQ
 
@@ -46,6 +47,8 @@ For other build methods read the sphinx documentation
 **How to edit and preview Restructured Text?**
 
 -   You can use [Atom](https://atom.io/) with the [RestructuredText Preview Pandoc](https://atom.io/packages/rst-preview-pandoc) Plugin
+-   [Typora](https://www.typora.io) is a friendly editor
+-   [Visual Studio Code](https://code.visualstudio.com) with the [reStructuredText](https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext) extension 
 
 **Release versions**
 

diff --git a/ci/texlive/texlive_packages b/ci/texlive/texlive_packages
@@ -18,4 +18,12 @@ upquote
 varwidth
 varwidth
 wrapfig
-xcolor
+anyfontsize
+xcolor
+kvoptions
+pdftexcmds
+epstopdf
+epstopdf-pkg 
+pdfescape
+letltxmacro
+bitset
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,4 @@
+sphinx>=1.9.0
+sphinx_rtd_theme
+sphinxcontrib-bibtex
+
diff --git a/source/about/manual/manual.rst b/source/about/manual/manual.rst
@@ -1,19 +1,10 @@
 About the manual
 ================
 
-This manual is a compilation of the resources found on alicevision.github.io, breadcrumbs of information collected from github issues, other web resources and new content, created for this manual.
-
-WORK IN PROGRESS! 
-(last update 03.06.19)
-
-
-
-
-You want to help? Missing something?
+This manual is a compilation of the resources found on alicevision.github.io, information collected from github issues, other web resources and new content, created for this manual. This manual is work in progress.
 
 You are welcome to comment and contribute. 
-This document is in “Suggest edits” mode.
-
+Check out https://github.com/alicevision/meshroom-manual/ for details.
 
 
 This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
@@ -23,4 +14,4 @@ This is a Meshroom community project.
 
 
 
-All product names, logos, and brands are property of their respective owners. All company, product and service names used in this document are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.
+All product names, logos, and brands are property of their respective owners. All company, product and service names used in this document are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.
diff --git a/source/about/meshroom/meshroom.rst b/source/about/meshroom/meshroom.rst
@@ -12,8 +12,8 @@ In 2009, the CMP research team from CTU started Michal Jancosek’s PhD thesis s
 
 In 2009, INPT, INRIA and Duran Duboi started a French ANR project to create a model based Camera Tracking solution based on natural features and a new marker design called CCTag.
 
-In 2015, Simula, INPT and Mikros Image joined their efforts in the EU project `POPART <http://www.popartproject.eu/>`_ to create a Previz system. In 2017, CTU joined the team in the EU project
-`LADIO <http://www.ladioproject.eu/>`_ to create a central hub with structured access to all data generated on set.
+In 2015, Simula, INPT and Mikros Image joined their efforts in the EU project `POPART <http://www.alicevision.org/popart>`_ to create a Previz system. In 2017, CTU joined the team in the EU project
+`LADIO <http://www.alicevision.org/ladio>`_ to create a central hub with structured access to all data generated on set.
 
 Partners
 --------
@@ -30,10 +30,10 @@ Partners
 
 `Quine <http://www.quine.no/>`_ in Oslo, Norway
 
-See Github authors for the full list of contributors.
+See `AliceVision Contributors <https://github.com/alicevision/AliceVision/blob/develop/CONTRIBUTORS.md>`_ for the full list of contributors.
 
-This project has received funding from the European Union’s Horizon 2020 research and innovation programme, see `POPART <http://www.popartproject.eu/>`_, Project ID: 644874 and
-`LADIO <http://www.ladioproject.eu/>`_, project ID: 731970.
+This project has received funding from the European Union’s Horizon 2020 research and innovation programme, see `POPART <http://www.alicevision.org/popart>`_, Project ID: 644874 and
+`LADIO <http://www.alicevision.org/ladio>`_, project ID: 731970.
 
 .. image:: eu.jpg
 

diff --git a/source/building/building.rst b/source/building/building.rst
@@ -0,0 +1,42 @@
+.. _building:
+
+Building Meshroom
+====================
+
+If you want to run the very latest version of Meshroom or some custom developer version, you need to get the sources.
+
+Software Environment
+~~~~~~~~~~~~~~~~~~~~
+
+Meshroom is a Python application and it relies on the `AliceVision <https://github.com/alicevision/AliceVision>`_ framework.
+
+
+Python Environment
+++++++++++++++++++
+
+The following versions of python are required:
+
+* Windows: Python 3 (>=3.5)
+
+* Linux / Mac OS X: Python 3 (>=3.5) or Python 2 (>= 2.7)
+
+.. note::
+  *No Python 2.7 support on Windows?*
+
+  Official Python 2.7 binary package is built with Visual Studio 2008, while PySide2/Qt is built using Visual Studio 2015/2017.
+  Therefore, in order to avoid mixing MSVC runtime libraries, Qt does not ship PySide2 wheels for Python 2.7 on Windows (as explained `here <https://wiki.qt.io/Qt_for_Python/Considerations#Missing_Windows_.2F_Python_2.7_release>`_).
+  Note that for using Meshroom in command line mode only (no UI), PySide2 is not required and Python 2.7 would be fine.
+
+
+Get the project
+~~~~~~~~~~~~~~~
+
+See `INSTALL.md <https://github.com/alicevision/meshroom/blob/develop/INSTALL.md>`_ to setup the project and prerequisites.
+
+Get the source code and install runtime requirements:
+
+.. code::
+
+  git clone --recursive git://github.com/alicevision/meshroom
+  cd meshroom
+  pip install -r requirements.txt
diff --git a/source/capturing/capturing.rst b/source/capturing/capturing.rst
@@ -24,10 +24,8 @@ Basics
 
 
 
-Details
--------
+**Details**
 
 
-Tutorials
----------
+**Tutorials**
 
diff --git a/source/conf.py b/source/conf.py
@@ -19,11 +19,14 @@
 
 import sphinx
 
+#after doing the `pip install sphinx_rtd_theme`with the Sphinx's version of Python
+import sphinx_rtd_theme
+
 # The master toctree document.
 master_doc = 'index'
 
 project = 'Meshroom'
-copyright = '2019, Meshroom Contributors'
+copyright = '2020. This work is licensed under a CC-BY-SA 4.0 International license.'
 author = 'Meshroom Contributors'
 
 # The full version, including alpha/beta/rc tags
@@ -35,7 +38,7 @@
 # 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.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosectionlabel', 'sphinx_rtd_theme', 'sphinxcontrib.bibtex']
 sphinxVersion = sphinx.version_info
 if(sphinxVersion[0] <= 1 and sphinxVersion[1] <= 8) :
 	extensions.append('sphinx.ext.pngmath')
@@ -57,13 +60,61 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes. sphinx_rtd_theme - search broken, table not soft break
 #
-html_theme = 'alabaster'
+#html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # 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']
+#html_static_path = ['_static']
+html_static_path = []
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 # html_logo = "mr_logo.png"
+
+# Latex/PDF generation Config
+# Based on hints from:
+# - https://stackoverflow.com/questions/54147210/how-to-add-copyright-notice-to-sphinx-generated-latex-documentation
+# - https://www.sphinx-doc.org/en/master/latex.html
+# - https://stackoverflow.com/questions/9745854/sphinx-pdf-themes
+# - https://digitalsuperpowers.com/blog/2019-02-16-publishing-ebook.html
+# - https://github.com/sphinx-doc/sphinx/pull/5850
+
+latex_contents = r'''
+    \setupHeadFootForFrontMatter
+    \formattoc
+    \maketitle
+    \signaturepage
+    \revisionhistory
+    \tableofcontents
+    \clearpage
+    \listoffigures
+    \clearpage
+    \listoftables
+    \clearpage
+    \setupHeadFootForText
+    \pagenumbering{arabic}
+    \pagestyle{plain}
+'''
+
+
+latex_elements = {
+    'fontpkg': r'''
+\usepackage{lmodern}
+''',
+    'preamble': r'''
+\newcommand\sphinxbackoftitlepage{%
+\vspace*{\fill}
+\begin{center}
+''' + u"\u00A9 " + copyright + r''' \\
+Revision: ''' + release + r''' \\
+\url{https://alicevision.org}
+\end{center}
+\vspace*{\fill}
+}
+'''
+}
+
+
+latex_show_urls = 'footnote'
diff --git a/source/copyright.rst b/source/copyright.rst
@@ -0,0 +1,6 @@
+Copyright
+=========
+
+Copyright 2020 Meshroom Contributors.
+
+Licensed under the Attribution-ShareAlike 4.0 International `CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0/>`_.
diff --git a/source/gui/augment-reconstruction/augment-reconstruction.rst b/source/gui/augment-reconstruction/augment-reconstruction.rst
@@ -1,3 +1,5 @@
+.. _augment-reconstruction:
+
 Augment Reconstruction
 ======================
 

diff --git a/source/gui/gui.rst b/source/gui/gui.rst
@@ -16,8 +16,9 @@ The Graphical User Interface (GUI)
 
 When you first start Meshroom, two windows open:
 
-the main graphical user interface with different panes
-and in the background the Command-line interface window.
+* the Command-line interface window (You can ignore or minimize this window. Do not close this window or Meshroom will terminate).
+* the main Graphical User Interface (GUI) with different panes:
+
 
 .. |01| image:: 01.jpg
 .. |02| image:: 02.jpg

diff --git a/source/gui/live-reconstruction/live-reconstruction.rst b/source/gui/live-reconstruction/live-reconstruction.rst
@@ -1,3 +1,5 @@
+.. _live-reconstruction:
+
 Live Reconstruction
 ===================