Skip to content

Commit

Permalink
Ghpages (#306)
Browse files Browse the repository at this point in the history
* Clone docs for gh pages

* Added nojekyll

* Update the docs

* Add new commands to the docs Makefile

* Change the way classes are displayed

* Follow the docs repo- removed library

* Whitelist for versioning

* Change the docstring parsing style (still numpy, but a different extension and change the directory for clean git in the Makefile (I do not want to accidentally delete it)

* Add placeholders for the readme and contribution guidelines

* Add theory page

* Add theory to the docs

* Add more recipes to the Makefile, for making docs

* Remove cleaning recipes, since they do not work, and are not needed  anyway

* Changes from docs

* Modify targers

* Add the theory rst (so as people do not have to pandoc, before make html)

* Sphinx gallery

* Add a readme for the functioning and structure of docs. Correct command in Makefile

* Commit the updated docs and add the gallery folders to git in the Makefille

* Ignore the output from sphinx-gallery, generated locally (to commit, move it to /docs)

* Exclude docs from flake8

* Remove docs as a submodule, change the directory of the docs folder

* Add scipy to intersphinx links

* New structure in the rst index

* Delete gallery-generated files

* Add versioning

* Refactor index

* Add creating a global index

* Push the new commit to origin

* Reproduce the structure of the landing page

* Change the title in the documented classes and functions

* Fix images submodule, and add contributions pages

* Add release notes, the example by Lewis, add afaq

* Add the rst faq file

* Try nbsphinx

* delete unused  readme and theory

* Correct the command for staging all changes in the docs,modify the import to cover the case where the examples are executedfrom a different directory

* Correct the start-after for examples, comment unnecessary ocnfig lines in conf

* Add mapper pipeline scheme in thedocs

* Work on the toctree structure (failed)

* Add a layout with a redirection link in the footer

* Add currentmodule scope when generating sphinx-doc for gtda.utils, add notebooks

* Adapt the Makefile to also work on CI (allow the variables to  be set externally

* Add azureidentity for git operations

* Change the nesting in yml CI

* Do not keep track of the glossary.rst

* Add strategy nesting in CI, silence remove glossary error and download picture if does not exist

* Add the python version to CI

* Add cache dir to variablles

* Unindent all of the steps in CI

* Correct git interactionsi nCI

* Correct indentation of azure

* Temporarily disabledownloading the token

* Correct the path of the figure

* Make jupyter notebooks display correctly in the docs

* Add before glossary, to get the right headings

* Ignore the incorporated notebooks and python files

* Add references, from the docstrings to the theory page

* Unify the beginning of notebooks in examples,so as to import the beginning in rst files

* Remove old notebooks readme

* Correct reference to the  voids on the plane notebook

* Modify the output in mapper-quickstart

* Restructure the hierarchy

* Change the hierarchy for the installation part

* Change link in the layout (still does not work?) and add the github url as metadata

* Change the add changes command for the gtda-docs repo

* Introduce a new index and  toctree structure

* Modify the structure,to get expandable items

* Introduce a vietorisRips quickstart

* Add notebooks to the new  ghpages structure, in two categories: basiic and advanceds

* Add examples,change references, work on the installation docs

* Correct the programatic staging of files in the docs repo

* Modify the docstrings in classes

* Reduce warnings on sphinx

* Reduce warnings with class templates

* Change location of the logo, suppress templates warnings

* Add the header required by pandoc for glossary

* Suppress warning for before_glossarynotincluded in toctrees

* Restructure the contributing documentation, add description of the doc infstrastrucure

* Change reference to dev installation and dealwith a no-new-line compilation warning

* Add the dev_installation and index files, for the new structure of contributing

* Add a prune-the-current-version target inthe makefile

* Modify the faq to something more official

* Prune the  donc conf file and add dependencies in the doc setup (anddev)

* Add openml to docs dependencies, and document depending on pandoc

* Add steps to check if the dependencies are installed correctly, before deleting everything from the clone

* Modify the docs CI stepo

* Correct the setup dependencies

* Fix some typos in the rst and tex - looking through the html

* Correct the layout in examples, move examples to use cases, rearange contributing

* Add a list of versions, add a target to statically fetch the available versions in the repo

* Detect the version automatically AND add it in the menu.Clean solution

* Correct indentation in the pipelines config file

* Use the pushing target from  the Makefile to push the documentation in the pipeline. Add a printout on make html

* Fix the pipeline url and prune CONTRIBUTING.rst

* Actually stage the changes of the contributing file

* Change the directory for cloning in azure

* Correct the pipeline linebreak syntax

* Change cloninig of gtdadocs from ssh to https

* Correct typo in password variable

* Reomve pushing to gtda-docs from makefile targets

* Disable failonStderr for git clone

* Correct GITDIR in pipelines

* Fix linting

* Wording changes in CONTRIBUTING.rst

* Update the previous versions with the currently compiled one

* Remove the .txt extension in sources for html files

* Remove failing on stdErr for generating noteebooks in CI and go back to 'stable' in the default version of docs generation

* Modify the push url in CI

* Add --repo option, capitalize variable

* Use quotes

* Add a section explaining the versioning in the docs

* Use ssh keys instead to push to gtda-docs

* Add logo to  images

* Define the pipelines to use  wreise/sphinx_rtd_theme

* Add installing the theme dependency in the docs

* Point to secure file on Azure

* Update ccache key

* Modify the windows dev installation instructions

* Modify how the installation is displayed

* Replace mapper pipeline svg, improve make_mapper_pipeline docstring

* Remove colons from subsection names in glossary

* Linting and fixing broken links in docstrings

* Point to GH pages from README.rst

* Remove the documentation ci (temporarily)

* Update ccache

* Fix environment problem in vietoris_rips_quickstart.ipynb

* Set the kernel to default in mapper_quickstart

* Clarify the sphinx_rtd_theme setup in contributing/index.rst

* Remove building docs in ci

* Add boost installation troubleshooting explanations

* Reintroduce PlotterMixin inheritance in VietorisRipsPersistence

Co-authored-by: Umberto <u.lupo@l2f.ch>
Co-authored-by: Umberto Lupo <46537483+ulupo@users.noreply.github.com>
  • Loading branch information
3 people committed Mar 12, 2020
1 parent f464a77 commit 6586676
Show file tree
Hide file tree
Showing 58 changed files with 14,467 additions and 760 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Expand Up @@ -22,6 +22,9 @@ data/*
# Built docs
doc/build
doc/generated
doc/gallery
doc/notebooks/*.ipynb
doc/notebooks/*.py

# Pybind11
gtda/externals/pybind11
Expand Down
125 changes: 5 additions & 120 deletions CONTRIBUTING.rst
@@ -1,123 +1,8 @@
Contributing guidelines
=======================

Pull Request Checklist
----------------------

Before sending your pull requests, make sure you followed this list.
- Read the `contributing guidelines <https://github.com/giotto-ai/giotto-tda/blob/master/GOVERNANCE.rst>`_.
- Read the `code of conduct <https://github.com/giotto-ai/giotto-tda/blob/master/CODE_OF_CONDUCT.rst>`_.
- Ensure you have signed the `contributor license agreement (CLA) <https://cla-assistant.io/giotto-ai/giotto-tda>`_.
- Check if the changes are consistent with the guidelines.
- Changes are consistent with the Coding Style.
- Run Unit Tests.

How to become a contributor and submit your own code
----------------------------------------------------

Contributor License Agreements
------------------------------

In order to become a contributor of giotto-tda, the first step is to sign the
`contributor license agreement (CLA) <https://cla-assistant.io/giotto-ai/giotto-tda>`_.
**NOTE**: Only original source code from you and other people that have signed
the CLA can be accepted into the main repository.

Contributing code
-----------------

If you have improvements to giotto-tda, do not hesitate to send us pull requests!
Please follow the Github how to (https://help.github.com/articles/using-pull-requests/).
The giotto-tda team will review your pull requests. Once the pull requests are approved and pass continuous integration checks, the
giotto-tda team will work on getting your pull request submitted to our GitHub
repository. Eventually, your pull request will be merged automatically on GitHub.
If you want to contribute, start working through the giotto-tda codebase,
navigate to the `GitHub issue tab <https://github.com/giotto-ai/giotto-tda/issues>`_
and start looking through interesting issues. These are issues that we believe
are particularly well suited for outside contributions, often because we
probably won't get to them right now. If you decide to start on an issue, leave
a comment so that other people know that you're working on it. If you want to
help out, but not alone, use the issue comment thread to coordinate.

Contribution guidelines and standards
-------------------------------------

Before sending your pull request for review, make sure your changes are
consistent with the guidelines and follow the coding style below.

General guidelines and philosophy for contribution
--------------------------------------------------

* Include unit tests when you contribute new features, as they help to
a) prove that your code works correctly, and
b) guard against future breaking changes to lower the maintenance cost.
* Bug fixes also generally require unit tests, because the presence of bugs
usually indicates insufficient test coverage.
* Keep API compatibility in mind when you change code in core giotto-tda.
* Clearly define your exceptions using the utils functions and test the exceptions.
* When you contribute a new feature to giotto-tda, the maintenance burden is   
(by default) transferred to the giotto-tda team. This means that the benefit   
of the contribution must be compared against the cost of maintaining the   
feature.

C++ coding style
----------------

Changes to giotto-tda's C/C++ code should conform to `Google C++ Style Guide <https://google.github.io/styleguide/cppguide.html>`_.
Use `clang-tidy` to check your C/C++ changes. To install `clang-tidy` on
ubuntu:16.04, do:


.. code-block:: bash
apt-get install -y clang-tidy
You can check a C/C++ file by doing:

.. code-block:: bash
clang-format <my_cc_file> --style=google > /tmp/my_cc_file.ccdiff <my_cc_file> /tmp/my_cc_file.cc
Python coding style
-------------------

Changes to giotto-tda's Python code should conform to PEP8 directives.
Use `flake8` to check your Python changes. To install `flake8` just do

.. code-block:: python
pip install flake8
You can use `flake8` on your python code via the following instructions:

.. code-block:: python
flake8 name_of_your_script.py
Git pre-commit hook
-------------------
We provide a pre-commit git hook to prevent accidental commits to the master branch. To activate, run

.. code-block:: bash
cd .git/hooks
ln -s ../../.tools/git-pre-commit pre-commit
Running unit tests
------------------

There are two ways to run unit tests for giotto-tda.

1. Using tools and libraries installed directly on your system. The election tool is `pytest`. To install `pytest` just do

.. code-block:: python
pip install pytest
You can use `pytest` on your python code via the following instructions:

.. code-block:: python
pytest name_of_your_script.py
2. Using Azure (azure-pipelines.yml) and giotto-tda's CI scripts.
This document only redirects to more `detailed instructions <https://giotto-ai.github.io/gtda-docs/dev/contributing>`_,
which consist of:
- a pull request checklist,
- a Contributor License Agreement,
- contributing guidelines and standards, including coding style guides.
49 changes: 27 additions & 22 deletions README.rst
Expand Up @@ -21,48 +21,48 @@
.. |Slack-join| image:: https://img.shields.io/badge/Slack-Join-yellow
.. _Slack-join: https://slack.giotto.ai/

==========
giotto-tda
==========

giotto-tda is a high performance topological machine learning toolbox in Python built on top of
scikit-learn and is distributed under the GNU AGPLv3 license. It is part of the `Giotto <https://github.com/giotto-ai>`_ family of open-source projects.

Project genesis
---------------
===============

giotto-tda is the result of a collaborative effort between `L2F SA
<https://www.l2f.ch/>`_, the `Laboratory for Topology and Neuroscience
<https://www.epfl.ch/labs/hessbellwald-lab/>`_ at EPFL, and the `Institute of Reconfigurable & Embedded Digital Systems (REDS)
<https://heig-vd.ch/en/research/reds>`_ of HEIG-VD.

License
-------
=======

giotto-tda is distributed under the AGPLv3 `license <https://github.com/giotto-ai/giotto-tda/blob/master/LICENSE>`_.
If you need a different distribution license, please contact the L2F team at
business@l2f.ch.

Documentation
-------------
=============

- API reference (stable release): https://docs-tda.giotto.ai
- Theory glossary: https://giotto.ai/theory
Please visit https://giotto-ai.github.io/gtda-docs and navigate to the version you are interested in.

Getting started
---------------
===============

To get started with giotto-tda, first follow the installations steps below. `This blog post <https://towardsdatascience.com/getting-started-with-giotto-learn-a-python-library-for-topological-machine-learning-451d88d2c4bc>`_, and references therein, offer a friendly introduction to the topic of topological machine learning and to the philosophy behind giotto-tda.

Tutorials and use cases
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------

Simple tutorials can be found in the `examples <https://github.com/giotto-ai/giotto-tda/tree/master/examples>`_ folder. For a wide selection of use cases and application domains, you can visit `this page <https://giotto.ai/learn/course-content>`_.

Installation
------------
============

Dependencies
~~~~~~~~~~~~
------------

The latest stable version of giotto-tda requires:

Expand All @@ -79,7 +79,7 @@ The latest stable version of giotto-tda requires:
To run the examples, jupyter is required.

User installation
~~~~~~~~~~~~~~~~~
-----------------

The simplest way to install giotto-tda is using ``pip`` ::

Expand All @@ -99,16 +99,18 @@ release) and hence does not require any C++ dependencies. As the main library mo
both the stable and nightly versions, giotto-tda and giotto-tda-nightly should not be installed in
the same environment.

.. _contributing-section:

Contributing
------------
============

We welcome new contributors of all experience levels. The Giotto
community goals are to be helpful, welcoming, and effective. To learn more about
making a contribution to giotto-tda, please see the `CONTRIBUTING.rst
<https://github.com/giotto-ai/giotto-tda/blob/master/CONTRIBUTING.rst>`_ file.

Developer installation
~~~~~~~~~~~~~~~~~~~~~~
----------------------

Installing both the PyPI release and source of giotto-tda in the same environment is not recommended since it is
known to cause conflicts with the C++ bindings.
Expand All @@ -123,7 +125,8 @@ Please refer to your system's instructions and to the `CMake <https://cmake.org/
`Boost <https://www.boost.org/doc/libs/1_72_0/more/getting_started/index.html>`_ websites for definitive guidance on how to install these dependencies. The instructions below are unofficial, please follow them at your own risk.

Linux
'''''
~~~~~

Most Linux systems should come with a suitable compiler pre-installed. For the other two dependencies, you may consider using your distribution's package manager, e.g. by running

.. code-block:: bash
Expand All @@ -133,15 +136,17 @@ Most Linux systems should come with a suitable compiler pre-installed. For the o
if ``apt-get`` is available in your system.

macOS
'''''
~~~~~

On macOS, you may consider using ``brew`` (https://brew.sh/) to install the dependencies as follows:

.. code-block:: bash
brew install gcc cmake boost
Windows
'''''''
~~~~~~~

On Windows, you will likely need to have `Visual Studio <https://visualstudio.microsoft.com/>`_ installed. At present,
it appears to be important to have a recent version of the VS C++ compiler. One way to check whether this is the case
is as follows: 1) open the VS Installer GUI; 2) under the "Installed" tab, click on "Modify" in the relevant VS
Expand All @@ -151,15 +156,15 @@ executables from the websites of the respective projects.


Source code
'''''''''''
~~~~~~~~~~~

You can obtain the latest state of the source code with the command::

git clone https://github.com/giotto-ai/giotto-tda.git


To install:
'''''''''''
~~~~~~~~~~~

.. code-block:: bash
Expand All @@ -170,7 +175,7 @@ This way, you can pull the library's latest changes and make them immediately av
Note: we recommend upgrading ``pip`` and ``setuptools`` to recent versions before installing in this way.

Testing
~~~~~~~
-------

After installation, you can launch the test suite from outside the
source directory::
Expand All @@ -179,24 +184,24 @@ source directory::


Changelog
---------
=========

See the `RELEASE.rst <https://github.com/giotto-ai/giotto-tda/blob/master/RELEASE.rst>`__ file
for a history of notable changes to giotto-tda.

Important links
~~~~~~~~~~~~~~~
---------------

- Official source code repo: https://github.com/giotto-ai/giotto-tda
- Download releases: https://pypi.org/project/giotto-tda/
- Issue tracker: https://github.com/giotto-ai/giotto-tda/issues

Community
---------
=========

giotto-ai Slack workspace: https://slack.giotto.ai/

Contacts
--------
========

maintainers@giotto.ai
22 changes: 3 additions & 19 deletions azure-pipelines.yml
Expand Up @@ -87,7 +87,7 @@ jobs:
displayName: 'Create download link'
inputs:
pathToPublish: '$(Build.ArtifactStagingDirectory)'
artifactName: 'wheel_and_doc'
artifactName: 'wheel'

- bash: |
set -e
Expand Down Expand Up @@ -188,22 +188,6 @@ jobs:
done
displayName: 'Test jupyter notebooks with papermill'
- script: |
set -e
cd doc/
make html
displayName: 'Build sphinx doc'
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: doc/build
includeRootFolder: true
archiveType: 'zip'
tarCompression: 'gz'
archiveFile: '$(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip'
replaceExistingArchive: true
displayName: 'Archive doc'

- task: CopyFiles@2
displayName: 'Copy files'
inputs:
Expand All @@ -214,7 +198,7 @@ jobs:
displayName: 'Create download link'
inputs:
pathToPublish: '$(Build.ArtifactStagingDirectory)'
artifactName: 'wheel_and_doc'
artifactName: 'wheel'

- bash: |
set -e
Expand Down Expand Up @@ -299,7 +283,7 @@ jobs:
displayName: 'Create download link'
inputs:
pathToPublish: '$(Build.ArtifactStagingDirectory)'
artifactName: 'wheel_and_doc'
artifactName: 'wheel'

- bash: |
set -e
Expand Down

0 comments on commit 6586676

Please sign in to comment.