Commit 6ba4670c authored by u214892's avatar u214892
Browse files

#174 #33 #149 cleanup sphinx

parent c33ad7a3
Pipeline #2054 passed with stages
in 29 minutes and 51 seconds
......@@ -61,10 +61,7 @@ test-all: ## run tests on every Python version with tox
tox
coverage: ## check code coverage quickly with the default Python
coverage run --source flatland -m pytest
coverage report -m
coverage html
$(BROWSER) htmlcov/index.html
python make_coverage.py
docs: ## generate Sphinx HTML documentation, including API docs
python make_docs.py
......
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
# TODO fix sphinx warnings instead of suppressing them...
SPHINXOPTS = -Q
SPHINXBUILD = python -msphinx
SPHINXPROJ = flatland
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=python -msphinx
)
set SOURCEDIR=.
set BUILDDIR=_build
set SPHINXPROJ=flatland
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
echo.then set the SPHINXBUILD environment variable to point to the full
echo.path of the 'sphinx-build' executable. Alternatively you may add the
echo.Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd
......@@ -66,7 +66,7 @@ class Environment:
The returns are dicts mapping from agent_id strings to values.
Parameters
-------
----------
action_dict : dict
Dictionary of actions to execute, indexed by agent id.
......
......@@ -36,8 +36,8 @@ class ObservationBuilder:
in the `handles' list.
Parameters
-------
handles : list of handles (optional)
----------
handles : list of handles, optional
List with the handles of the agents for which to compute the observation vector.
Returns
......@@ -57,8 +57,8 @@ class ObservationBuilder:
for each agent independently (agent id `handle').
Parameters
-------
handle : int (optional)
----------
handle : int, optional
Handle of the agent for which to compute the observation vector.
Returns
......
......@@ -33,11 +33,11 @@ class PredictionBuilder:
Called whenever get_many in the observation build is called.
Parameters
-------
----------
custom_args: dict
Implementation-dependent custom arguments, see the sub-classes.
handle : int (optional)
handle : int, optional
Handle of the agent for which to compute the observation vector.
Returns
......
......@@ -22,10 +22,10 @@ class DummyPredictorForRailEnv(PredictionBuilder):
Called whenever get_many in the observation build is called.
Parameters
-------
----------
custom_args: dict
Not used in this dummy implementation.
handle : int (optional)
handle : int, optional
Handle of the agent for which to compute the observation vector.
Returns
......@@ -96,10 +96,10 @@ class ShortestPathPredictorForRailEnv(PredictionBuilder):
Requires distance_map to extract the shortest path.
Parameters
-------
----------
custom_args: dict
- distance_map : dict
handle : int (optional)
handle : int, optional
Handle of the agent for which to compute the observation vector.
Returns
......
......@@ -114,7 +114,7 @@ class RailEnv(Environment):
Environment init.
Parameters
-------
----------
rail_generator : function
The rail_generator function is a function that takes the width,
height and agents handles of a rail environment, along with the number of times
......
......@@ -38,8 +38,10 @@ def complex_rail_generator(nr_start_goal=1,
max_dist=99999,
seed=0) -> RailGenerator:
"""
complex_rail_generator
Parameters
-------
----------
width : int
The width (number of cells) of the grid to generate.
height : int
......@@ -165,7 +167,7 @@ def rail_from_manual_specifications_generator(rail_spec):
transitions specifications.
Parameters
-------
----------
rail_spec : list of list of tuples
List (rows) of lists (columns) of tuples, each specifying a rail_spec_of_cell for
the RailEnv environment as (cell_type, rotation), with rotation being
......@@ -207,7 +209,7 @@ def rail_from_file(filename) -> RailGenerator:
Utility to load pickle file
Parameters
-------
----------
filename : Pickle file generated by env.save() or editor
Returns
......@@ -241,7 +243,7 @@ def rail_from_grid_transition_map(rail_map) -> RailGenerator:
16-bit transitions specifications.
Parameters
-------
----------
rail_map : GridTransitionMap object
GridTransitionMap object to return when the generator is called.
......@@ -277,7 +279,7 @@ def random_rail_generator(cell_type_relative_proportion=[1.0] * 11) -> RailGener
found to turn most un-genereatable levels into valid ones.
Parameters
-------
----------
width : int
The width (number of cells) of the grid to generate.
height : int
......@@ -527,11 +529,12 @@ def random_rail_generator(cell_type_relative_proportion=[1.0] * 11) -> RailGener
def sparse_rail_generator(num_cities=5, num_intersections=4, num_trainstations=2, min_node_dist=20, node_radius=2,
num_neighb=3, grid_mode=False, enhance_intersection=False, seed=0):
num_neighb=3, grid_mode=False, enhance_intersection=False, seed=0) -> RailGenerator:
"""
This is a level generator which generates complex sparse rail configurations
:param num_cities: Number of city node (can hold trainstations)
:type num_cities: int
:param num_intersections: Number of intersection that city nodes can connect to
:param num_trainstations: Total number of trainstations in env
:param min_node_dist: Minimal distance between nodes
......@@ -540,13 +543,10 @@ def sparse_rail_generator(num_cities=5, num_intersections=4, num_trainstations=2
:param grid_mode: True -> NOdes evenly distirbuted in env, False-> Random distribution of nodes
:param enhance_intersection: True -> Extra rail elements added at intersections
:param seed: Random Seed
:return:
-------
numpy.ndarray of type numpy.uint16
The matrix with the correct 16-bit bitmaps for each cell.
:return: numpy.ndarray of type numpy.uint16 -- The matrix with the correct 16-bit bitmaps for each cell.
"""
def generator(width, height, num_agents, num_resets=0):
def generator(width, height, num_agents, num_resets=0) -> RailGeneratorProduct:
if num_agents > num_trainstations:
num_agents = num_trainstations
......
......@@ -17,7 +17,7 @@ ScheduleGenerator = Callable[[GridTransitionMap, int, Optional[Any]], ScheduleGe
def speed_initialization_helper(nb_agents: int, speed_ratio_map: Mapping[float, float] = None) -> List[float]:
"""
Parameters
-------
----------
nb_agents : int
The number of agents to generate a speed for
speed_ratio_map : Mapping[float,float]
......@@ -120,7 +120,7 @@ def random_schedule_generator(speed_ratio_map: Mapping[float, float] = None) ->
Given a `rail' GridTransitionMap, return a random placement of agents (initial position, direction and target).
Parameters
-------
----------
rail : GridTransitionMap
The railway to place agents on.
num_agents : int
......@@ -213,7 +213,7 @@ def schedule_from_file(filename) -> ScheduleGenerator:
Utility to load pickle file
Parameters
-------
----------
input_file : Pickle file generated by env.save() or editor
Returns
......
......@@ -5,7 +5,7 @@ import shutil
import subprocess
import webbrowser
from urllib.request import pathname2url
from shutil import copyfile
def browser(pathname):
webbrowser.open("file:" + pathname2url(os.path.abspath(pathname)))
......@@ -22,17 +22,21 @@ def remove_exists(filename):
remove_exists('docs/flatland*.rst')
remove_exists('docs/modules.rst')
subprocess.call(['sphinx-apidoc', '--force', '-a', '-e', '-o', 'docs/', 'flatland', '-H', '"Flatland Reference"'])
# copy md files from root folder into docs folder
for file in glob.glob(r'./*.md'):
print(file)
shutil.copy(file, 'docs/')
subprocess.call(['sphinx-apidoc', '--force', '-a', '-e', '-o', 'docs/', 'flatland', '-H', '"Flatland Reference"'])
os.environ["SPHINXPROJ"] = "flatland"
os.chdir('docs')
subprocess.call(['python', '-msphinx', '-M', 'clean', '.', '_build'])
# TODO fix sphinx warnings instead of suppressing them...
subprocess.call(['python', '-msphinx', '-M', 'html', '.', '_build', '-Q'])
subprocess.call(['python', '-mpydeps', '../flatland', '-o', '_build/html/flatland.svg', '--no-config', '--noshow'])
subprocess.call(['python', '-msphinx', '-M', 'html', '.', '_build'])
#subprocess.call(['python', '-msphinx', '-M', 'html', '.', '_build', '-Q'])
# we do not currrently use pydeps, commented out https://gitlab.aicrowd.com/flatland/flatland/issues/149
# subprocess.call(['python', '-mpydeps', '../flatland', '-o', '_build/html/flatland.svg', '--no-config', '--noshow'])
browser('_build/html/index.html')
......@@ -4,9 +4,10 @@ wheel>=0.32.1
watchdog>=0.9.0
benchmarker>=4.0.1
coverage>=4.5.1
Sphinx>=1.8.1
# pin sphinx to <2.0 because of https://github.com/readthedocs/sphinx_rtd_theme/issues/746
Sphinx>=1.8.1,<2.0
sphinx-rtd-theme>=0.4.3
numpydoc
numpydoc>=0.9.1
docutils>=0.15.2
flake8>=3.7.7
flake8-eradicate>=0.2.0
......
......@@ -68,7 +68,7 @@ deps =
-r{toxinidir}/requirements_continuous_integration.txt
changedir = {toxinidir}
commands =
make coverage
python make_coverage.py
[testenv:benchmarks]
; use python3.6 because of incompatibility under Windows of the pycairo installed through conda for py37
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment