Until you install your own Python library

I will explain the procedure to install your own library with Python. It will not be published to PyPI and will be used within the team. Homebrew library name: mylibrary

Directory structure

The final directory structure is as follows.

./mylibrary
--- /mylibrary
    ---/__init__.py
        file1.py
        file2.py
--- /docs
    /makefile
     make.bat
     index.rst
     api.rst
     page1.rst
    ---/_static
       ---/icon.png
    ----/_build
        ---/html
--- /example
    ---/example1.py
        example2.py
lisence.txt
setpu.py

Directory description

mylibrary directory Place the source file.

__docs directory __ This is the directory where the library documents are placed. It is an empty directory at the time of creation. After creating the source file, use Sphinx to automatically create a document from the docstring in the source.

__examplede directory __ I will put the sample code of the library.

__setpu.py file __ This file describes the configuration at the time of installation.

__Other required files __ license.txt This is a file that describes the license.

Source file description

When creating a library, let's create a \ __ init__.py file. By creating a \ __ init__.py file, you will be able to import classes and functions in the library without using absolute paths.

notexist__init__.py

#__init__.If you install without creating py
from mylibrary.file1 import class1

You cannot import the class unless you describe the name of the folder in the library where the class is described.

_exist_init__.py

#__init__.If you create py
from mylibrary import class1

You can import the class by library name + class name. _init_.py

__init__.py

from .file1 import class1
from .file2 import class2
from .file3 import * 


__copyright__    = 'Copyright (C) 2018 Your Name'
__version__      = '1.0.0'
__license__      = 'BSD-3-Clause'
__author__       = 'Your Name'
__author_email__ = 'Your@Email'
__url__          = 'http://github.com/account/repository'

Description of setup.py

Execute the setup function of setpy.py to install. Add the necessary information at the time of installation. https://qiita.com/shinichi-takii/items/6d1063e0aa3f79e599f0 _init_.py

setup.py

from setuptools import setup
from os import path
import re

package_name = "package name"

root_dir = path.abspath(path.dirname(__file__))

def _requirements():
    return [name.rstrip() for name in open(path.join(root_dir, 'requirements.txt')).readlines()]


def _test_requirements():
    return [name.rstrip() for name in open(path.join(root_dir, 'test-requirements.txt')).readlines()]

with open(path.join(root_dir, package_name, '__init__.py')) as f:
    init_text = f.read()
    version = re.search(r'__version__\s*=\s*[\'\"](.+?)[\'\"]',init_text).group(1)
    license = re.search(r'__license__\s*=\s*[\'\"](.+?)[\'\"]',init_text).group(1)
    author = re.search(r'__author__\s*=\s*[\'\"](.+?)[\'\"]',init_text).group(1)
    author_email = re.search(r'__author_email__\s*=\s*[\'\"](.+?)[\'\"]',init_text).group(1)
    url = re.search(r'__url__\s*=\s*[\'\"](.+?)[\'\"]',init_text).group(1)

Automatically generate documents from docstring

It's a good idea to write the docstring in google style or numpy style. https://qiita.com/11ohina017/items/118b3b42b612e527dc1d

Install sphinx with pip. https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844 Then type the following command in the ./mylibrary directory (the one that doesn't contain the source):

sphinx-quickstart docs

Enter only the name of the project and the author as appropriate, otherwise there is no problem by default.

Move to __docs directory __ I think the conf.py file has been created. __ This is a file that describes the html settings created by sphinx. __

setup.py

import os
import sys
#Add source directory
sys.path.insert(0, os.path.abspath('../mylibrary'))
#Enable docstring creation function
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon','sphinx.ext.viewcode',
]
#html theme selection
html_theme = "blue"

Flask is a good reference for how to write setu.py. https://github.com/pallets/flask/blob/master/docs/conf.py You can download your favorite html theme from the following site. https://sphinx-themes.org/

Create an apidoc

Create an API reference.

sphinx-apidoc -f -o ./docs .

This will allow sphinx to scan the ./mylibrary directory where the source files are located and extract the classes for you.

Editing index and apidoc

You may want to divide the classes in apidoc that do not need to be exposed as API, or divide them into separate pages for each class instead of grouping them in apidoc. In that case, let's edit the rst file Editing the rst file is easy and removes unnecessary classes from the class list in apidoc.

__ Also, paste the link from the index.rst file to apidoc .__ __ If you forget this, building sphinx will not create an API reference __

index.rst

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   apidoc

Document build

Create an html file in the docs directory.

make html
#make for windows.bat html

This will create a sphinx-built hmtl page in docs / _build / html. You can use this directory as an API reference page by publishing it on netlify or github. If you want to create a more beautiful API reference, falsk's rst file creation method will be helpful. https://github.com/pallets/flask/tree/master/docs

Library installation

All you have to do is install the library.

python setup.py install

Thank you for your hard work!