WIP: add vitualenv doc

source/conf.py

@@ -33,7 +33,7 @@ intersphinx_disabled_domains = ["std"]
 
 
 templates_path = ["_templates"]
-exclude_patterns = []
+exclude_patterns = ["guide.rst"]
 
 language = "pt_BR"
 

source/guide.rst

+Hedears levels
+==============
 
-# with overline, for parts
+The headers level and order are::
 
-* with overline, for chapters
+  # with overline, for parts
+  * with overline, for chapters
+  = for sections
+  - for subsections
+  ^ for subsubsections
+  " for paragraphs
 
-= for sections
 
-- for subsections
+Contents tables
+===============
+There are two type of the do contents tables, with `contens` and `toctree`.
 
-^ for subsubsections
+`toctree`
+---------
+`toctree` are used to sumary between multiples files. 
 
-" for paragraphs
+**Example:**::
+  
+  .. toctree::
+    :maxdepth: `<level>`
+    :caption: `<caption>`
+    :glob: 
 
+Where:
+ * `<level>`: level of max depth content table.
+ * `<caption>`: The caption of the content table, this parameter are optional. 
+ * `<glob>`: Recursively
+
+
+`contents`
+----------
+`contents` are used to create *content table* only in the document.
+
+**Example:**::
+  .. contents::
+    :depth: `<level>`
+    :local:
+
+Where:
+  * `<level>`: level of max depth content table.
+  * `local`: set to show only index above the `.. contents`, if this parameter is omitted, will show all indexes.
+ 
+In this example will show *contents table* only with index above of the position the `.. contents`.
+
+
+
+Códigos
+=======
+
+There are two way to write codes in ``rst``, inline and block code. 
+
+Bloco de códigos
+----------------
+
+Block code are block of the code, to write in ``rst`` follow the template:::
+
+  .. code-block:: `<language>`
+     :caption: `<caption>`
+     :name: `<name>`
+
+Where:
+  * `<language>`: The language of the code to activate highlight of the syntax.
+  * `<name>`: The ``name`` directive is like the ``label`` in latex, then is to reference. Must be a
+    string without space or special characteres.
+
+
+Notes
+=====
+
+Notes are box with text, threre are diferents types of the notes, which changes the color and style.
+
+Tips
+----
+
+``tip`` and ``hint`` are used to highlight information that has a positive effect for users, or to
+inform a an alternative features. To use ``tip`` or ``hint``.
+
+Example: tip:
+^^^^^^^^^^^^^
+
+To use ``tip`` follow this template:::
+
+  .. tip:: 
+
+    A note text
+
+Example: hint:
+^^^^^^^^^^^^^^
+
+To use ``hint`` follow this template:::
+
+  .. hint:: 
+
+    A note text
 

source/pages/application.rst

-##########
-Aplicações
-##########
+##################
+Guias e aplicações
+##################
 
 .. toctree::
   :maxdepth: 1
   :caption: Aplicações
+  :glob: 
 
-  ml.rst
+  applications/*

source/pages/applications/env_management.rst

+*************************
+Gerenciadores de ambiente
+*************************
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Gerenciadores de ambientes
+   :glob:
+
+   env_management/*
+
+    

source/pages/applications/env_management/python.rst

+=====================================
+Gerenciadores de ambiente para python
+=====================================
+
+Gerenciadores de ambiente permite que você possua em seu computador ou conta aplicações com
+multiplas versões de pacotes e até mesmo diferente versão do intrepetador *python*.
+
+.. contents::
+   :depth: 1
+   :local:
+
+
+Virtualenv
+----------
+
+Virtualenv é um utilitário para criar ambientes python isolado do sistema. Desde a versão ``3.3``
+parte do virtualenv é nativo do python, pelo `módulo venv <https://docs.python.org/3/library/venv.html>`_.
+
+Instalação
+^^^^^^^^^^
+O pacote ``virtualenv`` está disponível tanto em módule, ``module load virtualenv`` quanto é
+possível instalar via ``pip``. 
+
+Instalar localmente com ``pip``:
+""""""""""""""""""""""""""""""""
+Para instalar via pip no seu usuário execute o comando: ``pip --user install virtualenv``. Exemplo:
+
+.. code-block:: shell
+   :caption: Exemplo de instalação do virtualenv 
+   :name: install-virtualenv-local
+
+    [odair@c3hpc:doc/virtualenv ]$ module load python/3.9.7
+    [odair@c3hpc:doc/virtualenv ]$ pip install virtualenv
+    Collecting virtualenv
+      Downloading virtualenv-20.16.7-py3-none-any.whl (8.8 MB)
+           |████████████████████████████████| 8.8 MB 7.2 MB/s
+    Requirement already satisfied: distlib<1,>=0.3.6 in
+    /home/odair/.local/lib/python3.9/site-packages (from virtualenv) (0.3.6)
+    Requirement already satisfied: filelock<4,>=3.4.1 in
+    /home/odair/.local/lib/python3.9/site-packages (from virtualenv) (3.8.0)
+    Requirement already satisfied: platformdirs<3,>=2.4 in
+    /home/odair/.local/lib/python3.9/site-packages (from virtualenv) (2.5.2)
+    Installing collected packages: virtualenv
+    Successfully installed virtualenv-20.16.7
+    [odair@c3hpc:doc/virtualenv ]$
+
+É possível conferir  se foi instalado e a versão com o comando ``virtualenv --version``, como no
+exemplo avaixo:
+
+.. code-block:: shell
+   :name: check-virtualenv-version-local
+
+    [odair@c3hpc:doc/virtualenv ]$ virtualenv --version
+    virtualenv 20.16.7 from /home/odair/.local/lib/python3.9/site-packages/virtualenv/__init__.py
+    [odair@c3hpc:doc/virtualenv ]$
+
+.. note::
+
+   | Executar o comando ``pip install virtualenv`` vai instalar o ``virtualenv`` na home do seu  usuário, dentro do diretório ``${HOME}/local``, então caso não funcione o virtualenv veja se a  variável de ambiente ``PATH`` inclui o caminho ``${HOME}/.local/bin/`` caso contrário adicione  o comando abaixo:
+   | ``echo 'PATH=${PATH}:${HOME}/.local/bin' >> ${HOME}/.bashrc && source ${HOME}/.bashrc``
+
+Criar ambiente:
+^^^^^^^^^^^^^^^
+Para criar um ambiente com ``virtualenv`` use o comando ``virtualenv venv``. Exemplo:
+
+.. code-block:: shell
+   :caption: Exemplo de como cirar ambiente com virtualenv
+   :name: create-env-virtualenv
+
+    [odair@c3hpc:doc/virtualenv ]$ virtualenv venv
+    created virtual environment CPython3.9.2.final.0-64 in 1767ms
+      creator CPython3Posix(dest=/home/odair/doc/virtualenv/venv, clear=False, no_vcs_ignore=False, global=False)
+      seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/home/odair/.local/share/virtualenv)
+        added seed packages: pip==22.1.2, setuptools==62.3.2, wheel==0.37.1
+      activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
+    [odair@c3hpc:doc/virtualenv ]$ ls
+    venv
+    [odair@c3hpc:doc/virtualenv ]$
+
+O virtualenv cria um diretório chamado ``venv`` no qual contêm os arquivos de ativação.
+
+
+Ativar ambiente:
+^^^^^^^^^^^^^^^^
+Para ativar o ambiente com virtualenv execute o comando: ``source <env>/bin/activate``, onde `<env>`
+é o diretório criado pelo virtualenv, normalmente ele se chama **venv**. Exemplo de ativação:
+
+.. code-block:: shell
+   :caption: Exemplo de como ativar virtualenv
+   :name: activate-virtualenv
+
+    [odair@c3hpc:doc/virtualenv ]$ ls
+    venv
+    [odair@c3hpc:doc/virtualenv ]$ source venv/bin/activate
+    (venv) [odair@c3hpc:doc/virtualenv ]$
+
+Note que apareceu ``(venv)`` ao lado da linha de comando, isso indica que você está com o ambiente
+ativado.
+
+Desativar ambiente:
+^^^^^^^^^^^^^^^^^^^
+Para desativar o ambiente execute o comando ``deactivate``. Exemplo:
+
+.. code-block:: shell
+   :caption: Exemplo de como desativar o virtualenv
+   :name: deactivate-virtualenv
+
+    (venv) [odair@c3hpc:doc/virtualenv ]$ deactivate
+    [odair@c3hpc:doc/virtualenv ]$
+
+Note que desapareceu ``(venv)`` ao lado da linha de comando, isso indica que o ambiente está desativado.
+
+Gerenciar pacotes no ambiente:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+O `virtualenv` utiliza o `pip` para gerencia os módulos e biblioteca, o único requisito é estar com o ambiente ativado.
+ 
+Instalação:
+"""""""""""
+Para instalar pacotes com ambiente `virtualenv` entre no ambiente e instale normalmente com `pip`.
+
+Por exemplo para instalar os pacotes pandas e numpy execute a segunte sequência de comandos:
+
+.. code-block:: shell
+   :caption: Instalação dos módulos pandas e numpy dentro do ambiente do virtualenv
+   :name: install-pandas-numpy-virtualenv
+
+    [odair@c3hpc:doc/virtualenv ]$ source venv/bin/activate
+    (venv) [odair@c3hpc:doc/virtualenv ]$ pip install pandas numpy
+    Collecting pandas
+      Downloading pandas-1.5.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.2 MB)
+         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 12.2/12.2 MB 44.6 MB/s eta 0:00:00
+    Collecting numpy
+      Downloading numpy-1.23.5-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.1 MB)
+         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.1/17.1 MB 45.3 MB/s eta 0:00:00
+    Collecting python-dateutil>=2.8.1
+      Using cached python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
+    Collecting pytz>=2020.1
+      Downloading pytz-2022.6-py2.py3-none-any.whl (498 kB)
+         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 498.1/498.1 kB 15.1 MB/s eta 0:00:00
+    Collecting six>=1.5
+      Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
+    Installing collected packages: pytz, six, numpy, python-dateutil, pandas
+    Successfully installed numpy-1.23.5 pandas-1.5.2 python-dateutil-2.8.2 pytz-2022.6 six-1.16.0
+
+    [notice] A new release of pip available: 22.1.2 -> 22.3.1
+    [notice] To update, run: pip install --upgrade pip
+    (venv) [odair@c3hpc:doc/virtualenv ]$
+
+Para verificar se realmente foi instalado os módulos você pode simplemente executar um arquivo que
+importe o módulo ou verificar a versão, como é feito abaixo:
+
+.. code-block:: python3
+   :caption: Verificando se os modulos foram instalados,
+   :name: virtualenv-check-module-is-installed,
+
+    (venv) [odair@c3hpc:doc/virtualenv ]$ python -c "
+    import pandas as pd
+    import numpy as np
+    print('Versão pandas instalada: ',pd.__version__)
+    print('Versão numpy instalada: ',np.__version__)
+    "
+    Versão pandas instalada:  1.5.2
+    Versão numpy instalada:  1.23.5
+    (venv) [odair@c3hpc:doc/virtualenv ]$
+
+
+Remover pacotes:
+""""""""""""""""
+Para remover pacotes ative o `virtualenv` e execute o comando `pip uninstall <pacote>` onde `<pacote>` é o nome do módulo que deseja remover. Exemplo:
+
+.. code-block:: shell
+   :caption: Remove biblioteca numpy do ambiente
+   :name: uninstall-numpy-virtual-env
+
+    (venv) [odair@c3hpc:doc/virtualenv ]$ pip uninstall numpy
+    Found existing installation: numpy 1.23.5
+    Uninstalling numpy-1.23.5:
+      Would remove:
+        /home/odair/doc/virtualenv/venv/bin/f2py
+        /home/odair/doc/virtualenv/venv/bin/f2py3
+        /home/odair/doc/virtualenv/venv/bin/f2py3.9
+        /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy-1.23.5.dist-info/*
+        /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy.libs/libgfortran-040039e1.so.5.0.0
+        /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy.libs/libopenblas64_p-r0-742d56dc.3.20.so
+        /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy.libs/libquadmath-96973f99.so.0.0.0
+        /home/odair/doc/virtualenv/venv/lib/python3.9/site-packages/numpy/*
+      Proceed (Y/n)? y
+        Successfully uninstalled numpy-1.23.5
+
+Veja agora se executar o comando abaixo ele vai dizer que `numpy` não existe, portanto, foi removido.
+
+.. code-block:: shell
+   :caption: Verificando se a biblioteca numpy foi removida.
+   :name: check-numpy-is-uninstalled-virtualenv
+
+    (venv) [odair@c3hpc:doc/virtualenv ]$ python -c "
+    import numpy as np
+    print('Versão numpy instalada: ',np.__version__)
+    "
+     Traceback (most recent call last):
+      File "<string>", line 2, in <module>
+     ModuleNotFoundError: No module named 'numpy'
+     (venv) [odair@c3hpc:doc/virtualenv ]$
+
+
+Gerar requeriments.txt
+""""""""""""""""""""""
+Para gerar o arquivo `requeriments.txt` entre no ambiente do virtualenv e execute o comando ``pip
+freeze > requirements.txt``. Exemplo:
+
+.. code-block:: shell
+   :caption: Gerando o arquivo requirements.txt
+   :name: vitualenv-generate.requirements.txt
+
+    (venv) [odair@c3hpc:doc/virtualenv ]$ pip freeze > requeriments.txt
+    (venv) [odair@c3hpc:doc/virtualenv ]$ cat requeriments.txt
+    pandas==1.5.2
+    python-dateutil==2.8.2
+    pytz==2022.6
+    six==1.16.0
+    (venv) [odair@c3hpc:doc/virtualenv ]$
+
+
+Execução de aplicações
+^^^^^^^^^^^^^^^^^^^^^^
+O *virtualenv* só permite executação de dentro do ambiente. Então, para rodar aplicações com o
+*slurm* e o virtualenv se sugere as seguintes opções:
+
+.. contents::
+   :local:
+   :depth: 1
+
+Ativar o ambiente e executar a aplicação
+""""""""""""""""""""""""""""""""""""""""
+
+Ativar o ambiente no script `sbatch`
+""""""""""""""""""""""""""""""""""""
+
+Dicas e recomendações:
+^^^^^^^^^^^^^^^^^^^^^^
+
+Pipenv
+------
+
+Criar ambiente:
+^^^^^^^^^^^^^^^
+
+Ativar ambiente:
+^^^^^^^^^^^^^^^^
+
+Desativar ambiente:
+^^^^^^^^^^^^^^^^^^^
+
+Executar aplicações dentro e fora do ambiente:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Gerenciar pacotes no ambiente:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dicas e recomendações:
+^^^^^^^^^^^^^^^^^^^^^^
+
+Poetry
+------
+
+Criar ambiente:
+^^^^^^^^^^^^^^^
+
+Ativar ambiente:
+^^^^^^^^^^^^^^^^
+
+Desativar ambiente:
+^^^^^^^^^^^^^^^^^^^
+
+Executar aplicações dentro e fora do ambiente:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Gerenciar pacotes no ambiente:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dicas e recomendações:
+^^^^^^^^^^^^^^^^^^^^^^
+
+Anaconda
+--------
+
+Criar ambiente:
+^^^^^^^^^^^^^^^
+
+Ativar ambiente:
+^^^^^^^^^^^^^^^^
+
+Desativar ambiente:
+^^^^^^^^^^^^^^^^^^^
+
+Executar aplicações dentro e fora do ambiente:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Gerenciar pacotes no ambiente:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dicas e recomendações:
+^^^^^^^^^^^^^^^^^^^^^^
+

source/pages/ml.rst → source/pages/applications/machine_learning.rst

@@ -4,6 +4,7 @@ Machine learning
 
 .. toctree::
   :maxdepth: 1
-  :caption: Primeiros passos
+  :caption: Exemplos de aplicações de *Machine learning*
+  :glob:
 
-  keras.rst
+  machine_learning/*

source/pages/keras.rst → source/pages/applications/machine_learning/keras.rst

@@ -122,11 +122,11 @@ Para iniciar um ambiente python com pipenv utilize o comando `pipenv shell`.
    :caption: iniciando um ambiente python com pipenv
    :name: pipenv-start-env
 
-  [odair@c3hpc:~/deepdream ]$ pipenv shell
-  Launching subshell in virtual environment...
-   . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate
-   [odair@c3hpc:~/deepdream ]$  . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate
-  deepdream [odair@c3hpc:~/deepdream ]$
+    [odair@c3hpc:~/deepdream ]$ pipenv shell
+    Launching subshell in virtual environment...
+     . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate
+    [odair@c3hpc:~/deepdream ]$  . /home/odair/.local/share/virtualenvs/deepdream-djfpP2vq/bin/activate
+    deepdream [odair@c3hpc:~/deepdream ]$
 
 É possível executar código python sem que esteja dentro do ambiente, com o comando `pipenv run
 <file>` o pipenv vai iniciar o ambiente, executar código contido em `file` e sair do ambiente.

source/pages/basic.rst

@@ -5,7 +5,6 @@ Primeiros passos
 .. toctree::
   :maxdepth: 1
   :caption: Primeiros passos
+  :glob:
 
-  acesso.rst
-  overview.rst
-  quickstart.rst
+  quickstart/*

source/pages/overview.rst → source/pages/quickstart/overview.rst

@@ -10,7 +10,7 @@ Fluxo de trabalho do HPC
 O primeiro passo é entender como o cluster e executar programas em computadores de alto desempenho funciona.
 
 
-.. figure:: ../_static/hpc-slurm.svg
+.. figure:: ../../_static/hpc-slurm.svg
     :alt: Diagrama de funcionamento de computação de alto desempenho.
 
 O uso de HPC para realizar processamento paralelo e de alto desempenho consiste em:

source/pages/quickstart.rst → source/pages/quickstart/quickstart.rst

@@ -15,11 +15,9 @@ Principais parâmetros de submissão:
     * ``-n NUM_PROCESSOS``  Especifica o número de processos a serem iniciados.
     * ``-N NUM_NODOS`` Especifica que deverão ser alocados pelo menos NUM_NODOS nodos para a execução do job, ou seja, cada nodo vai executar NUM_PROCESSOS dividido por NUM_NODOS.
     * ``–job-name=NOME`` Especifica o nome do Job que será executado. Este nome irá aparecer juntamente com o id do job na listagem de jobs do sistema.
-    * ``-e`` Especifica o redirecionamento do stderr. Exemplo:
-    ``-e arquivoErros.txt``
+    * ``-e`` Especifica o redirecionamento do stderr. Exemplo: ``-e arquivoErros.txt``
+    * ``-o``  Especifica o redirecionamento do stdout. Caso ``-e`` não tenha sido especificado, stderr também será enviado para o arquivo especificado. Exemplo: ``-o arquivoSaida.txt`` ou ``--output arquivoSaida.txt``
 
-    * ``-o``  Especifica o redirecionamento do stdout. Caso ``-e`` não tenha sido especificado, stderr também será enviado para o arquivo especificado. Exemplo:
-    ``-o arquivoSaida.txt`` ou ``--output arquivoSaida.txt``
 Comando *srun* 
 ==============
 | O comando ``srun`` submete um *job* para o escalonador, por padrão esse comando é bloqueante. A sintaxe do comando é:
@@ -76,7 +74,8 @@ Comando *sbatch*
 Abaixo, um exemplo de script que roda a aplicação “meuPrograma” que está no diretório bin. A aplicação irá executar por no máximo 7 dias e é solicitado 1 nodo para a execução.
 
 .. code-block:: bash
-   #!/bin/sh
+
+    #!/bin/sh
     #SBATCH -p 7d
     #SBATCH -t 7-00:00:00
     #SBATCH -n 1